Retro over the refuter reports

/plan-retro turns the findings of every /refute run into proposed changes to the repository's rules. A finding the refuter keeps making is a rule the builder was not given, or was given where the brief did not point, or was given in words the builders misread, or, for a fact a machine computes, is a check nobody runs. It leaves behind a retro report in the ledger and, for each proposal the user approves, the edit it proposes, committed together.

Quick start

/plan-retro             the retro over every refuter run the previous retro did not list
/plan-retro <project>   the same, for one project of a plan.yaml in the projects: form

Use instead

What it reads

1. .agents/plan.yaml, its required keys and defaults as /plan states them: ledger_root, archive_root, rules, standards, verification.
   • A required key missing is a refusal ("Stops").
2. Every refuter report under <ledger_root>/ and <archive_root>/, each agents/reviews/<step>-refuter.md, leaving out the runs the previous retro lists under "Reports read" (Steps 1).
3. The newest file under <ledger_root>/retros/ named <YYYY-MM-DD>.md, the previous retro, for its "Reports read" list. With no previous retro, every run is read.
4. The rules page, every page in standards, and the verification page, whole.
5. For a finding whose kind is unclear from its text, the report it came from and the brief of its step.

Steps

1. Read each report "What it reads" 2 lists, run by run: the first review, under its Spec, Proof, Standards and Behaviour headings, and each section "Repair round <n>, refuted".
   • Each finding is an item "Grouping" keeps, noted with its plan, step, report, run, heading, location and text.
   • The runs the previous retro's "Reports read" lists are left out unless the user asks for a retro over everything.
     • They are matched by plan folder, step and run, so a plan moved into <archive_root> stays left out and a round added to a report later is read.
   • A previous retro that cannot be read as UTF-8, has no ## Reports read heading, or holds a line there that is not an entry in the form of templates/retro.md stops the retro there, a refusal ("Stops").
2. Assign each finding one kind, as "Grouping" says.
3. For each kind, count the findings, the distinct steps and the distinct plans.
4. Name the heading each kind's findings fell under.
5. Quote two or three findings of each kind with their report path and location.
6. Mark the recurring kinds: a kind other than "no defect" is recurring when it appears in at least three steps, or in at least two plans.
7. For each recurring kind, draft the proposal, as "The proposal for a recurring kind" says.
8. Write <ledger_root>/retros/<YYYY-MM-DD>.md from templates/retro.md.
   • The reports read: each report a finding came from, with its path under <ledger_root> or <archive_root> (<plan>/agents/reviews/<step>-refuter.md) and the runs its findings came from, as templates/retro.md shows.
   • The previous retro's "Reports read" entries, carried over, so a run listed once stays skipped by every later retro.
     • A report in both lists has its runs joined in one entry.
   • A run that gave no finding has no entry; the next retro reads it again, and it gives none again.
   • The counts by heading, of the findings left after the "no defect" set-aside.
   • The recurring kinds, each with its counts, its quoted findings and its proposal.
   • Then the other kinds, "no defect" apart, with their counts and no proposal.
   • Then the findings set aside as "no defect", with their own count, each with its report path, location and text, and no proposal.
9. Show the retro to the user.
10. Take the user's decision on each proposal, one by one: approved, corrected or declined ("Stops").
11. Write each decision beside its proposal in the retro.
12. Make the approved edits: the rules page, a standards page, the text that should have prevented the defect, .agents/plan.yaml, the verification page, and, for an approved check of a fact, its script.
13. Run each approved check's command.
14. Show each command's output.
15. Commit the retro and the edited files in one commit whose subject names the retro.
    • Each file is staged with git add -- <path> ....
    • The commit names the same paths: git commit -m <message> -- <path> ....

Grouping

• A kind is a sentence that states the defect in general terms, the way a rule would forbid it: "a test that cannot fail", "a comment that names the step that wrote it", "a document sentence the diff makes false".
• Findings whose text reports the same defect in different words share a kind.
• unclassified findings from repair rounds are read and assigned like the rest, or set aside when they are a point the reviewer did not check.
• The session keeps as a finding, whatever its text says, every top-level item under a Spec, Proof, Standards or Behaviour heading and every item of a repair round outside the parts it does not read: the list before a round's subheadings when one of them is Spec, Proof, Standards or Behaviour, the Verification, Verdicts, Declined to judge, Not checked, Closed, Closures and Usage lists, and fenced lines.
• A finding whose text reports no defect (a confirmation such as "None." or "No sentence in the pages is made false") or a closure that holds (such as "Spec 1: closed.") is set aside, by reading, as the kind "no defect".
  • It is counted and listed in the retro's "No defect" section with no proposal.

The proposal for a recurring kind

The skill checks where the rule should have come from, in this order, and proposes the first change of 1 to 3 that applies; a check is proposed only as 4 says:

1. The rule is not written anywhere. Grep the rules page and the standards pages for it.
   • When it is absent, the proposal is the rule's text, in the voice and numbering of the page it goes into (the rules page for how a change is made and reported, a standards page for what the code or prose looks like), with the findings it would have prevented cited.
2. The rule is written on a page the briefs do not point at. When the rule is on a page that is neither the rules page nor listed in standards, the proposal adds the page to standards in .agents/plan.yaml.
3. The rule is written where the briefs point, and the defect still recurs. The proposal is a sharper sentence for the existing rule, or a change to the text that should have prevented the defect (a brief template, a skill's step).
   • It quotes the findings that show how builders read the current text.
4. Whether the rule is kept is a fact a machine computes. Only then may the proposal add a check beside the change of 3: a grep over the diff, a lint rule or a script over the tree.
   • It states what the check computes, its command, the output it gives on the current tree, and the line to add to the verification page so every step runs it.
   • The user's decision on the proposal approves what it computes, before it is written.
   • A rule whose breach is judged by reading gets no check.

Stops

• The first row is a stop: it waits on the user.
• The second and third rows are refusals: each names its cause and changes nothing.

Anti-patterns

Rules

• The skill reads the ledgers and never edits a report, a brief or a plan.
• Counts come from the findings listed in the retro, each with its report and location, and the grouping written there.
• A proposed rule states what to do and at most one clause of why.
• A proposed rule carries no date, no incident and no step number; the retro file is where those live.