resolve-section-ownership

Resolve Section Ownership

Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.

This is the ownership counterpart to break-down-func-spec. That skill splits one functional spec into several because it is too large; this one moves facts between sections because they are in the wrong place. The two are unrelated: a correctly placed spec can be too large, and a one-line bullet can be misplaced.

When to Use

• A bullet answers more than one of what is it, what does it do, how is it built, how is it tested.
• A requirement states a mechanism (retry, cache, token refresh, connection handling) but sits in ***functional specs***.
• A :UnitTests: fact sits in ***test reqs***, or a :ConformanceTests: fact sits in ***implementation reqs*** — the generators read only their own section, so the fact is silently ignored today.
• A functional spec describes an external system rather than the software being built.
• A whole file is being audited for placement.

When Not to Use

• The spec is correctly placed but too large → analyze-if-func-spec-too-complex, then break-down-func-spec.
• Two specs contradict each other → analyze-func-specs, then resolve-spec-conflict.
• The wording is merely verbose → trim per concise-specs.md; no fact changes section.

Input

The bullet, section, or .plain file to resolve.

Workflow

1. Read the full .plain file — every section, plus its import and requires chains, so an existing home for a fact is visible before a new one is written.
2. Identify the target — one bullet, one section, or the whole file.
3. Decompose each bullet into atomic facts. A clause joined by and, which, so that, or a comma often carries a second fact. Keep each fact in the author's own words for now; rewording comes at step 6.
4. Route each fact by the Section ownership table in module-structure.md. Where a fact resists the table, apply the question it encodes: would a caller of the finished software observe this? Yes → ***functional specs***. No, it is how the result is reached → ***implementation reqs***. It says what a term means → ***definitions***. It shapes :ConformanceTests: → ***test reqs***.
5. Split a fact that carries both a mechanism and its consequence. The consequence is observable and becomes the functional spec; the mechanism becomes the implementation req. "Sends the same idempotency key on every retry, so a retried write creates at most one record" is two facts, not one.
6. Give each moved fact a subject that exists in the built system. A fact leaving a functional spec often loses its subject: name the component that owns the behavior, and add it to ***definitions*** if it is not defined yet. :Implementation: is the whole codebase — use it only for a fact that holds everywhere.
7. Author each fact into its owning section with the right edit skill — add-concept, add-implementation-requirement, add-test-requirement, add-acceptance-test. Never hand-author ***functional specs***: a fact moving into that section goes through add-functional-spec, which runs the complexity and conflict analyzers for you.
8. Remove each fact from where it no longer belongs. If a bullet is left stating nothing observable, delete the bullet; do not leave a stub. Deleting the last bullet of a section deletes the section.
9. Verify nothing was lost and nothing was duplicated. Walk every fact from the original text and confirm it appears in exactly one section. A fact that now reads as obvious in its new home is still a cut decision — make it deliberately, per concise-specs.md.
10. Run plain-healthcheck. Moving facts changes the renderable surface; do not finish on a FAIL.
11. Read the file again to confirm canonical section order (***definitions*** → ***implementation reqs*** → ***test reqs*** → ***functional specs***), correct syntax, and that every referenced concept is still defined before use.