Shard single responsibility and idea mitosis

Merlon Docs treats documentation as library science for software product intent: settle a concept, give it one place to live, and keep that place small enough that a human or agent can load it alone without being misled.

The focal rule is shard single responsibility for a documentation shard. How shards assemble into guides is secondary. Frameworks that informed this thinking are listed in Acknowledgments — they are provenance, not the instruction set.

The merlon-docs skill states these rules for agents, in the QA principles of SKILL.md and in skills/merlon-docs/references/shard-responsibility.md, because every install gets a copy of those files. Agent Skill names the skill as their owner. This page explains the rules in more depth. No check compares the three copies with each other or with the glossary entry shard single responsibility, so keeping the four in step is advisory (Enforceable rules): whoever changes a rule changes all four, and the change’s review is the evidence.

Single responsibility rule

A documentation shard has one primary concern, for one audience, serving one job. In the Code Repository Archetype, one audience means one guide tier.

Axis	Question	Failure mode
Concern	What one settled idea does this file own?	Two capabilities that drift on different schedules
Audience	Who needs this — consumer or contributor?	Mixing client usage with maintainer runbooks
Job	Explain, instruct how-to, or define/look up — not all	Explanation pasted into a step list, or the reverse

Reason to change: a shard should have one main reason to be edited. If product contract language and “run these five commands” must change for different events, they do not belong in the same file.

Complete for that job: the shard is finished when a reader can use it for its job without the rest of the compiled guide and without being misled. Completeness is not a line-count budget. Glossary leaves may be three lines; a single contract may need a longer section and still be one responsibility.

These rules are advisory: merlon check passes a shard with two responsibilities. merlon review flags candidates with three of its signals: long-shard, similar-titles and duplicate-paragraph, and with --strict it exits 1 on any finding. The doc-review workflow decides each candidate, and its commits are the evidence.

Splitting a shard (idea mitosis)

When pressure builds along more than one axis, split the shard instead of letting it grow. Splitting a shard this way is idea mitosis.

Split when

Dual audience — consumers and contributors both “need this paragraph” → apply the placement test; usually features/client vs developer.
Dual job — understanding why mixed with how to do it or with look-up facts → separate explanation, how-to/runbook, and reference/definition shards.
Dual concern — two independent capabilities or decisions → one shard each.
Load failure — reading the file alone misleads → extract the missing concern or merge with the sibling that must travel with it (mitosis can also mean “these two were never separate organisms”).
Unsettled next to settled — discovery notes, spikes, or time-bound reactions sitting beside current durable truth → discovery stays in the issue tracker; durable shards stay current only.

Do not split when

Headings that are still one reason to change (for example Inputs and Outputs of the same contract, or Preconditions and Steps of the same how-to). That is structure inside one responsibility, not a second organism.

After a split

Update the guide index.md (or shards.md) so compile order stays intentional.
Cross-link daughter shards; do not leave orphaned halves.
Run two-level review: each shard in isolation, then the guide as a whole.

Guides (secondary)

A guide is an ordered constellation of shards for one audience job family (in the Code Repository Archetype: features, client, developer, glossary). Compile stitches them for reading; shards remain the source of truth.

Organize a guide so that:

Each shard still passes single responsibility.
Manifest order tells a coherent story for that audience without requiring every reader to load every shard.
Each shard passes the placement test.

The SRP and mitosis rules apply under every archetype, whatever its guide names.

Two-level review

When a change touches documentation (or code whose behavior a guide documents):

In isolation — each changed idea or shard is locally correct for its single responsibility.
Comprehensively — against related shards and guides: duplication, better splits/merges/relocations, and agreement between what guides promise and what the change does.

A review is complete only when the change and its guides agree. Guides record the intent behind the code, so a review of the diff alone can miss where they disagree. To review a whole docs root as a set, use the doc-review workflow.

Supporting maps (optional depth)

Use these maps when judging job or settledness. Agents do not need the full frameworks to obey SRP — the tables are aids.

Documentation job (needs)

Job	Typical durable home
Learn by doing (guided)	Client getting-started / onboarding
Achieve a goal (steps)	Client how-tos; developer runbooks
Look up facts	CLI/config reference; glossary; contracts
Understand why / how it fits	Features, ADRs, design constraints

Mixing two jobs in one shard is a mitosis signal. Named lineage: Acknowledgments.

Settledness

State	Durable shard?
Known, short definition	Yes — often glossary or a small reference leaf
Analyzable contracts / design	Yes — feature/client/developer shard
Only knowable by probing	Not yet — spike, issue, draft; promote when settled
Incident / crisis notes	No — tracker / ops, not durable guides

Extensions beyond this archetype

Go-to-market documentation, such as marketing and sales docs, falls outside the Code Repository Archetype. A project that keeps it in the same repository defines its own guide tiers for it, as Extensions and archetypes says.

Acceptance

Authors and agents can state a shard’s single responsibility in one sentence.
Mitosis decisions cite audience, job, or concern — not file length alone.
Guide indexes reflect splits; two-level review runs when guides are involved.
Provenance for external frameworks lives in Acknowledgments, not in the operative skill rules.