Shard responsibility (agent reference)
Operative rules for when to write, split, or leave durable Merlon Docs shards. Keep this file short. Provenance: see acknowledgments.md.
Single responsibility
Section titled “Single responsibility”A shard has one primary concern, for one audience (features / client / developer / glossary in the Code Repository Archetype), serving one job (explain or instruct how-to or define/look up — not several).
If you cannot state that responsibility in one sentence, the shard is not ready — or it needs mitosis.
Idea mitosis — split when
Section titled “Idea mitosis — split when”- Dual audience (consumer vs contributor)
- Dual job (explain vs how-to vs reference)
- Dual concern (independent reasons to change)
- Reading the file alone misleads
- Unsettled discovery / time-bound notes next to durable current truth → move discovery to the issue tracker
Do not split only because a file is long. Split because responsibility multiplied.
After split
Section titled “After split”Update the guide index, cross-link, then two-level review (isolation, then guide agreement).
Guides
Section titled “Guides”A guide orders shards for one audience job family. Each shard still obeys single responsibility. Placement is by audience and job, not topic keyword alone.