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. "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.

• 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

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.