Folk tradition: "Run X means run X after Y and Z"

Folk tradition knowledge is the undocumented institutional lore that accumulates around every long-lived codebase.

·Critical knowledge exists only in people's heads (tribal knowledge)
·Documentation is outdated or nonexistent (nobody writes docs because nobody reads them)

·Team acknowledges that tribal knowledge is a risk
·Some informal knowledge sharing exists (Slack threads, meeting notes)

Evidence

·Documentation audit showing outdated or missing docs for key systems
·Onboarding feedback citing reliance on "ask someone" for critical information

What It Is

Folk tradition knowledge is the undocumented institutional lore that accumulates around every long-lived codebase. "Run the tests" doesn't mean just run the tests — it means first stop the local Redis container, then set the TEST_ENV flag, then run the tests, then restart Redis, because someone learned this the hard way in 2019 and told exactly two people. The command itself is documented. The preconditions are not. They live in the heads of the people who have been burned by skipping them.

This pattern shows up everywhere in mature codebases: deployment scripts with undocumented preconditions, build commands that silently assume a specific tool version, database migration steps that break if run outside a VPN. Each of these represents a gap between the nominal procedure and the actual procedure — a gap maintained exclusively through oral transmission from senior to junior, Slack message to Slack message, onboarding buddy to new hire.

The consequences compound over time. Each undocumented precondition is a trap waiting for the next person who doesn't know it. When that person is a human new hire, the cost is a few hours of confusion and a Slack message to the right senior. When that person is an AI agent, the cost is a failed deployment, a broken test suite, or a corrupted environment — with no path to recovery because the agent has no way to discover what it doesn't know.

At L1, these folk traditions are invisible to the organization as a problem. They feel like "just how things work." Nobody has quantified the cost of maintaining them, and nobody has a systematic view of how many such traps exist in the codebase. The knowledge is there — it just lives in the wrong place.

Why It Matters

Agents cannot access oral tradition - an AI agent given run the tests will run the tests, hit the silent precondition, fail in a confusing way, and have no path to the tribal knowledge that would have prevented the failure
Bus factor is hidden - each undocumented precondition has an owner, usually a senior engineer; when they leave or are unavailable, the trap becomes a crisis rather than a speedbump
Onboarding cost is invisible - new engineers lose days or weeks discovering folk traditions through trial and error; this cost is real but never attributed to documentation debt
Codebase drift accelerates the problem - every refactor and dependency change has a chance to invalidate existing folk traditions and create new ones; without a forcing function to write them down, the inventory only grows
Context windows cannot hold oral history - even if agents had access to all your Slack history, extracting reliable procedural knowledge from years of conversational messages is not a solved problem

Getting Started

Run a "traps audit" - spend one sprint asking every engineer to write down one undocumented precondition they know about: commands that require specific setup, processes with hidden dependencies, "everyone knows you have to" statements. Collect these in a shared doc and treat the count as a baseline metric.
Instrument failures - when a CI job fails due to environment setup rather than code bugs, require the post-mortem to include a documentation update. This creates a forcing function: every trap that fires gets documented.
Pair on onboarding to surface traps - have a senior engineer watch silently while a new hire follows the setup instructions literally. Every place the new hire gets stuck is a folk tradition that needs to be written down.
Convert Slack knowledge to docs - search for recurring Slack threads where seniors answer the same setup questions. Each one is a folk tradition masquerading as a support ticket. Extract the answer and add it to the relevant documentation.
Add preconditions to runbooks explicitly - wherever you have a procedure, add a "Prerequisites" section. Make it a team norm that procedures without prerequisites sections are considered incomplete.
Tag undocumented commands in CI - add a comment format to your CI configuration that flags commands with hidden preconditions: # PREREQ: requires TEST_ENV=true and Redis stopped. This makes the implicit explicit in the place where it matters most.

Tip

The most reliable way to find folk traditions is to watch someone follow instructions literally. Senior engineers are blind to their own tribal knowledge - they automatically perform the preconditions without noticing. A new engineer or a rubber duck reveals every gap.

6 steps to get from here to the next level

Common Pitfalls

Treating documentation as a one-time cleanup. Teams often run a "doc sprint" to capture existing folk traditions and then declare victory. Within months, new folk traditions have accumulated because the underlying culture hasn't changed. Documentation of procedures must be a continuous norm enforced by review process and team culture, not a periodic catch-up activity.

Writing down what to do without writing down why. Documenting "stop Redis before running tests" without explaining why (because the integration test suite conflicts with a running Redis instance on the default port) means the next engineer who reorganizes the test suite won't know to preserve the precondition. The why is often more valuable than the what.

Assuming seniors will document their own knowledge. Seniors are the least likely people to notice their own tribal knowledge — to them, it's just obvious. Documentation of folk traditions requires deliberate extraction mechanisms: pairing with new hires, requiring post-mortems, mandatory prerequisites sections. Voluntary documentation by seniors rarely closes the gap.

Under-scoping the problem to the README. Folk traditions live in every runbook, every CI configuration comment, every deployment script header. Treating the README as the canonical place for all procedural knowledge creates a document that grows unmanageably and still doesn't cover the long tail of undocumented preconditions.

Not updating documentation when procedures change. Folk tradition documentation that has drifted from reality is worse than no documentation — it creates false confidence. Every procedure change must include a documentation update as part of the definition of done, not as an afterthought.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has a team of 40 engineers across 6 teams. He estimates that onboarding takes 3 months to full productivity, but he has never quantified how much of that time is spent discovering folk traditions versus genuinely learning the domain. He suspects it's a lot. When he tries to push for better documentation, he gets pushback from seniors who say they don't have time.

What Bob should do: Bob should run the traps audit as a structured initiative, framing it as a productivity investment rather than a documentation chore. The output is a count: how many folk traditions exist, how often they fire, and who owns them. This count is the business case. If 40 engineers each lose 2 hours per month to folk tradition traps (a conservative estimate for a 3-year-old codebase), that's 80 hours of productivity lost monthly. Documenting the 20 highest-impact traps is a day of work that pays back in weeks. Bob should make "eliminate one folk tradition per sprint" a team-level commitment for every team, with the count tracked as a leading indicator of documentation health.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has been measuring time-to-productivity for new engineers and has noticed that the fastest onboarders are the ones assigned to seniors who proactively share tribal knowledge. The slowest onboarders are left to figure things out from the documented procedures. This tells her the documented procedures are missing critical information, but she hasn't been able to quantify exactly what's missing.

What Sarah should do: Sarah should instrument the onboarding process with a structured "trap journal" - a doc that new engineers fill out during their first 60 days, recording every time they got stuck on something that wasn't in the docs. After 3-4 new hires complete this, Sarah will have a ranked list of the highest-impact folk traditions. She should then track documentation coverage: what percentage of the items in the trap journal have been added to official documentation? This metric — trap documentation rate — is a leading indicator for whether the organization is closing the gap or letting it grow. Share it with Bob monthly.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor is trying to integrate AI agents into the team's development workflow, but he keeps hitting a wall: agents fail in confusing ways because they encounter undocumented preconditions that every human engineer knows about but nobody has written down. The agents aren't broken — the documentation is. Victor needs to fix the documentation before the agents can work reliably.

What Victor should do: Victor should treat every agent failure as a documentation bug. When an agent fails because it didn't know to stop Redis first, that's a missing prerequisites section, not an agent failure. Victor should keep a running list of agent failures caused by missing context and use it as a prioritized documentation backlog. Each item he documents not only fixes the agent workflow — it also fixes the human onboarding experience. Victor should make this case explicitly to the team: "every fix I make to help agents work reliably is also a fix that makes onboarding faster." This framing gets documentation work done faster than framing it as infrastructure investment alone.

What Victor should do - role-specific action plan