seam-guide-readmes

name	seam-guide-readmes
description	Anchor top-level before/after/foundation folders with short README files so later work extends the intended seam instead of guessing.
domain	repository-structure
confidence	medium
source	earned

Context

Use this pattern when a repo is deliberately split into top-level seams such as before, after, foundation, or shared data folders. It is most useful early in a project, when the directory structure exists but downstream contributors still need a crisp rule for where new material belongs.

Patterns

• Put a short README.md at the root of each major seam (docs, docs\foundation, src, data\sqlserver, and similar roots).
• Describe the ownership boundary of the folder, not a full implementation plan.
• Use the README to explain why the seam exists and what kinds of artifacts belong there.
• Keep the text stable and architectural so it survives later implementation detail churn.

Examples

• docs\README.md explains the split between legacy, target-state, and foundation documentation.
• docs\foundation\README.md states that scenario, naming, and package baselines live there.
• src\README.md makes the migration-state split explicit so before and after do not collapse into one code tree.

Anti-Patterns

• Relying on one root README to explain every folder in a growing repo.
• Letting teams infer folder meaning from issue titles or tribal memory.
• Writing folder READMEs that duplicate volatile implementation details instead of documenting the seam.