section-by-section

This skill reviews one instruction file, the target, with the user. It first works through the target section by section, and each section closes with one or more verdicts. It then puts the closed sections back together. It checks whether the whole file delivers its purpose, the intent anchor fixed at Start, and proposes fixes to the arrangement where it does not.

Closure law. The skill proposes; the user closes. A section is closed when the user gives its verdicts and approves any replacement text they carry. A gap and the outline (Assembly step 3) are closed when the user approves their text. No verdict the user did not give reaches the ledger. Every "closed" below means this.

Check-table law. Every diagnosis, and every text this skill proposes for the draft, including the outline and the composed draft, shows a check table with three columns: Check, Looked at, Result.

• One row per check, every time: redundancy, responsibility, coherence, ambiguity, correctness, clarity, pointers, names, form, deletions. Diagnose defines each check. Correctness runs only on a diagnosis, because it needs evidence that new text cannot have. Deletions runs only on proposed text.
• Looked at names what the check examined: the words, the lines, the other section. A bare clean is not a result.
• Rows keep the order above, so a missing row shows. Each table has nine rows: a diagnosis leaves out deletions, and proposed text leaves out correctness.
• On a diagnosis, each finding ends in → and its verdict. On proposed text, each row ends in what changed. The table covers the whole text, including words kept from the old version, and each check reads the text against itself as well as the rest of the file. At Compose it covers only the joins, since closed text was already checked.

Start

Read the target whole. The user gives it by path: a SKILL.md, an agent file, or a file in a skill's references/ folder when the user names that file.

Then post one setup message. Diagnose no section until the user has answered every item it asks about, however many replies that takes.

The setup message carries four things:

• Intent anchor. Ask the user, in their own words, what this file exists to make an agent do. Show no line of your own yet. From the reply, write one line and ask the user to confirm it. Once confirmed, it is fixed: it does not change for the rest of the run, and every check below measures against it.
• Section map. A list covering the file end to end, one line of summary each.
  • Ids: S1..Sn in file order, and DESC for the frontmatter description. A SPLIT verdict later yields S3a and S3b.
  • Divide by heading; where there are none, by numbered step; failing those, by paragraph. Divide further any heading that carries its own named or numbered steps, or runs past about thirty lines: by its steps, or else by paragraph.
  • The user confirms the map, joins or divides entries, and names the review scope: the whole file or named sections.
• Paths. The draft and the ledger. Default: the session's scratch directory; where the runtime has none, ask for one.
• Observations and outside files. Ask how the file behaved: a transcript excerpt, a failure, a complaint; there may be none. Ids are O1..On. Then ask which other files the target relies on. The redundancy, pointers and names checks read those files, and no other file outside the target. No answer means none.

Asking is always open. Ask before going on when:

• the review scope or a section boundary is unclear;
• the description and the body disagree about what the file does;
• an observation contradicts the intent anchor.

Markers

Three markers, which are not verdicts:

Section loop

For each in-scope section, in file order:

DIAGNOSE → SETTLE → WRITE → APPROVE → RECORD → next section
you        user     you     user      you
  ↑          │        ↑        │
  └──────────┘        └────────┘
  not a closure       text sent back

Verdicts that carry no text go from SETTLE straight to RECORD.

Diagnose

Run every check below except deletions, reading the section against the rest of the section map, each closed section in its closed form. Each finding carries its verdict. A section takes:

• at most one placement verdict: REMOVE, SPLIT, MERGE or MOVE;
• any number of wording verdicts: REPLACE, RESHAPE, COMPRESS, REWORD;
• KEEP alone, when no check finds anything.

REMOVE takes no wording verdict. SPLIT takes none either: each half is diagnosed on its own and takes its own verdicts.

Post the diagnosis, with no replacement text yet, in this order:

1. A heading: <id> — Diagnosed (<title>, <line range>).
2. The current text, quoted, or summarised when it runs past ten lines.
3. What the section makes an agent do, in one line.
4. The check table.
5. The verdicts, naming any MERGE partner, MOVE destination or SPLIT boundary, and for a clash, the other section and the change it takes.
6. The evidence: observation ids, rulings, or this run.
7. One question asking the user to close.

Redundancy

Meaning carried nowhere else, in this file or a named outside file; different wording is not different meaning.

• The whole section is said elsewhere, or the intent anchor needs none of it → REMOVE.
• Some sentences are said elsewhere or not needed → COMPRESS: cut them. This includes a definition that repeats what its word already says. A sentence two sections share is cut only from the one Responsibility says does not own it.

A line written to stop a recorded failure is not redundant unless evidence shows the failure is gone.

Responsibility

One question → one owning section. Run it per sentence.

• The section answers two questions → SPLIT. Diagnose the halves at once, in order, before the next section.
• Another section already answers its question → MERGE into that owner. Never hide an ownership conflict by rewording one of the two.
• One sentence answers another section's question → COMPRESS: cut it here. The owner takes it at its closure, or in this section's Write step if the owner is already closed.
• Its question is its own but it sits in the wrong place → MOVE; the move itself changes no words. A wrong place is a wrong position, a wrong file, or this file for detail only some runs need: that detail goes one level down, into a references/ file beside the draft.
• Its own question needs something it does not say → REWORD when a phrase is missing, GAP when an instruction is.

Coherence

Every instruction here can be obeyed alongside every other section's.

• Two sections clash → name both, and propose which one changes and with which verdict. The user closes both. The one that stands takes no verdict from this finding. A section the loop has not reached yet takes its change when the loop reaches it; unclosed, both carry to Assembly.

Ambiguity

Every sentence has one reading.

• A sentence has a second reading → REWORD. The Result cell writes out the second reading.

Correctness

Following it produces the right result. Judged only on evidence: an observation, a ruling the user made in this run, a failure this run hit, a worked case, or a checked fact.

• Evidence shows it produces the wrong result → REPLACE: a different instruction takes its place. For a worked case, the Result cell shows the input and the wrong output; for a checked fact, what was checked and found.

Clarity

Direct, self-consistent, actable without interpretation.

• It says its one thing in more words than it needs → COMPRESS.
• It contradicts itself → REWORD: same instruction, clearer words.
• It asks for judgment where a concrete test exists → REWORD: state the test.

Pointers

Every reference reaches its target.

• A reference to a section, step, file or term does not resolve, or resolves to the wrong thing → REWORD: point at the real target.

Names

One word for one meaning, one meaning for one word.

• A term the reader cannot know is not defined at its first use, one term stands for two things, two terms stand for one thing, or a name is too narrow for its uses → REWORD.

Form

The shape fits the content.

• The content is a list, parallel cases, a sequence or a single rule, in a shape that does not match; a fence reads as a template to fill; or the heading does not name what the section does → RESHAPE. Compare with sections of the same kind in this file.

Deletions

Every cut from the old text is named, with why nothing needed is lost.

• A cut drops something the intent anchor needs → put it back before showing the text.

Settle

A reaction is not a verdict. At SETTLE or APPROVE, the user's reply closes, holds (see Markers), or does neither.

• A closure: the user gives the verdicts or approves the text; a yes to a question that names them counts. If the yes leaves a choice open, name the reading taken; the next reply confirms or corrects it.
• A reopening: the user reopens a closed section. It goes through the loop again from DIAGNOSE.
• Anything else: answer any question, then restate the proposal against the reply and ask again. A correction may overturn the diagnosis, not only the wording. One that applies beyond this section is a ruling: add it to the Rulings list when made.

Write

At each verdict that carries text, write the shortest text that needs no decoding. KEEP, REMOVE and a MOVE within the file carry none. A KEEP section enters the draft as it stands when it closes. A SPLIT carries none itself; its halves enter at their own closures. A MERGE's text is written at the partner's closure, or here when the partner is already closed.

Post it in this order:

1. A heading: <id> — Proposed.
2. The text.
3. The check table.
4. One question asking the user to approve.

The text reaches the draft once, when the user approves it. A MOVE to another file is written into a second file beside the draft, named for the destination file it feeds and never the draft's own path.

Record

The ledger opens with the intent anchor, the observation ids, the named outside files, the review scope, and a Rulings list (R1..Rn, empty at the start). Every later proposal names any ruling it bends.

Then a row for each closure, each GAP found and each UNREVIEWED section, written before the next proposal or Assembly step:

| id | title | verdicts | reason | evidence | detail |

• id: the section id, or — for a GAP.
• verdicts: the placement verdict first.
• reason: why it closed, in the user's words where they differ.
• evidence: observation ids, ruling ids, or this run.
• detail: what the verdicts carry, or —.

A gap that closes, or a section that closes again, takes a new row; a written row is never amended.

Assembly

Assembly asks whether the closed sections, put back together, deliver the intent anchor: every question owned once, nothing left unanswered, and an arrangement in which the reader meets each thing when they need it.

It changes no closed section on its own: a finding re-enters as a proposal, and the user closes it as in the loop.

Where the scope was named sections, more sections join here: any that share a question, a reference or an overlapping instruction with a reviewed one, or must be read before it or after it. A section the user closes here loses its UNREVIEWED line.

1. HOLD and GAP. Every held section takes its verdicts. Every open gap takes proposed text the user approves, or stays a gap in the ledger.
2. Every diagnosis check, over the whole file. Resolve each finding as in the loop; in a clash, the intent anchor says which section departs. Correctness here is a worked case run through the draft from start to finish.

3. Verify. Against the intent anchor:

   • Show the outline: one line per surviving section, in the proposed arrangement: what an agent acts on first at the top, prohibitions and finish conditions at the bottom.
   • Check the description against what the body now does: third person, what the file does and when to use it.

   Show each with its check table. The user closes the description under DESC, then the outline, as shown or with the changes named. The outline places each MOVE closed in the loop where its closure said; a reorder the user closes here takes a MOVE row.

4. Compose. Write the draft whole, in the closed arrangement. Closed text is copied as approved; only the joins between sections are new. Every file this run produces stays under 500 lines: when the body passes it, propose moving detail only some runs need one level down (see Responsibility); when a references/ file passes it, propose splitting that file. Compose again once those proposals close. Show the draft with a check table that covers the joins.

Hand-off

Deliver the draft, the ledger, and any second file a MOVE to another file produced. Name the observations no verdict cited. Then stop.

Prohibitions

Never write to the target path. Every change lands in the draft.