Diagnose a defect

/diagnose finds the cause of a symptom with a command that is red on it, before any theory. It leaves behind the cause, stated with the probe that shows it, the fix with its test, and the diagnosis record, which holds every command and result of the run.

Quick start

/diagnose <symptom>                        find the cause of a symptom, given in the user's words, in the checkout the skill is run in
/diagnose <entry> <step> <finding>         find the cause of a finding of a plan's step, written as the refuter report names it
/diagnose <entry> <step> red line          find the cause of a red line at the step's landing whose cause is not known
/diagnose <entry> <step> brief check <n>   find the cause of finding <n> of the step's brief check
/diagnose <entry> <step> premise           find the cause a step's text asks to have found, before the step's brief is written

Use instead

What it reads

1. The symptom, quoted exactly.
   • For /diagnose <symptom>, the user's words.
   • For a finding, the failure scenario in the report that holds it.
   • For premise, what the step's text says happens, in each part of the text that asks for a cause to be found.
     • The words of such a part vary, as in "find why X happens and end it" and "find the cause of X and fix it".
     • The step's text is its line in plan.md's step list, the rulings its tags name and its Step 0.
2. The rules file and the standards .agents/plan.yaml names, docs/glossary.md and the ADRs in force as the spec skill's "What it reads" 5 says, each when the repository has it.
   • With no rules file, "Rules" states the rules this skill needs.
3. Inside a plan, the ledger folder and orchestrator-state.md.
   • <entry> resolves to its folder as the spec skill's "What it reads" 2 says.
   • No such folder is a refusal ("Stops").
   • For a finding of a reviewer's report and for a red line, the dispatch entry for the step names the worktree and the base.
   • For a red line, the entry reads landing: backed-out: a red line the landing could not fix on main has taken the step back out of main, as the land skill's Steps 6 says.
   • For a reviewer's finding or a red line, no dispatch entry for the step, or one that reads landing: preparing, is a refusal ("Stops").
   • For a red line, an entry that does not read landing: backed-out is a refusal too.
   • A brief-check finding is diagnosed while the step's dispatch entry reads landing: preparing, and no dispatch entry is read for it.
   • For premise, plan.md holds the step's text (item 1).
     • The rulings its tags name are resolved as the spec skill's "What it reads" 4 resolves them, (self-rule) endings included.
   • premise runs while the step's dispatch entry reads landing: preparing, and reads no dispatch entry and no brief, since the step is not prepared yet.
   • For premise, a step that is not in the step list is the refusal "No part to investigate" ("Stops").
4. Inside a plan, for every form but premise, the step's brief agents/briefs/<step>.md.
5. Inside a plan, for every form but premise, the report the finding is in.
   • For a finding written as a heading and a number, the refuter report agents/reviews/<step>-refuter.md: the finding of that name in the first run, before any heading "Repair round <n>, refuted".
   • For a finding written round <n> and a heading and a number, the finding of that name under the heading "Repair round <n>, refuted" of the same report.
   • For brief check <n>, the brief check's report agents/reviews/<step>-brief-check.md, read as it stands on disk.
   • For red line, the failure the step's landing recorded under the step's Step 0 in plan.md, and the open item in the state file when the landing booked one, which land Steps 6 does only when what to do is a decision for the user.
   • No such report or finding is a refusal ("Stops").

Steps

1. Inside a plan, refuse when "What it reads" 3 or 5 finds an input missing.
   • For premise, refuse also when the step's text holds no part that asks for a cause to be found, before the record is opened.
   • Done when every input inside a plan exists, or the refusal names the missing one, or for premise the step and its text.
2. Open the diagnosis record with the symptom quoted in its Symptom section.
   • Outside a plan, the record is a copy of templates/diagnosis.md in $TMPDIR, filled as the steps below run.
   • Inside a plan, the record is agents/reviews/<step>-diagnosis.md beside the state file, a copy of templates/diagnosis.md filled as the steps below run.
   • A diagnosis agent fills a copy of templates/diagnosis.md in $TMPDIR, and the session saves that record at the path above from the agent's final message ("Rules").
   • A later diagnosis of the same step is appended to that file under its own heading at the level of the record's title, # Diagnosis: <the symptom in a few words>, which names its finding or quotes its part.
   • For premise, each part of the step's text that asks for a cause to be found gets a diagnosis of its own, in the order of the step's text, the first filling the record as opened.
   • Inside a plan, the record is written to disk in the main checkout and not committed on its own, except as Steps 20 says for premise.
     • The next resume-point commit of its own plan carries it, as plan-orchestration's "Resuming, and handing the plan over" says.
   • Done when the record exists and its Symptom section holds the symptom as "What it reads" 1 gives it, word for word.
3. Choose where the probes run.
   • Write into the record's "Where the probes run" section what the choice names.
   • Outside a plan, the probes run in the user's checkout or worktree.
   • Outside a plan, a defect that is not on the checkout (an older commit, with or without a patch) gets a scratch copy built as the next bullets say, run by a person too.
     • <commit> is that commit.
     • The patch, read from where the user names it, is applied with the last line of the block.
   • Inside a plan, the probes run on a scratch copy under $TMPDIR that shares no file with the step's worktree.
   • $tmp is made by mktemp -d "${TMPDIR:-/tmp}/diagnose.XXXXXX".
   • The copy is a detached worktree made from the main checkout.
   • The commands for each source of the defect are these.

     tmp=$(mktemp -d "${TMPDIR:-/tmp}/diagnose.XXXXXX")
     git worktree add --detach "$tmp/tree" <commit>                # from the main checkout
     git diff --binary <base>                                      # a reviewer's finding: from inside the step's worktree, saved to "$tmp/step.diff"
     git apply --allow-empty "$tmp/step.diff"                      # a reviewer's finding: from inside "$tmp/tree"
     git status --porcelain --untracked-files=all                  # a reviewer's finding: from inside the step's worktree, listing the files to copy
     git diff --binary <base> <branch>                             # a red line: from the main checkout, saved to "$tmp/step.diff"
     git apply --3way --allow-empty "$tmp/step.diff"               # a red line: from inside "$tmp/tree"
     git apply --3way --allow-empty <patch>                        # outside a plan, a defect at an older commit with a patch: from inside "$tmp/tree"

   • For a finding of a reviewer's report:
     • <commit> is the dispatch entry's base.
     • The step's diff is taken from inside the step's worktree.
     • Each file listed with ?? is copied to the same path in the copy.
   • For a red line, <commit> is HEAD and the step's whole range is taken from the branch of the kept worktree, which is named after the worktree's folder as the land skill's "Removing a step's worktree" says.
   • --allow-empty lets a step whose only changes are new files, with an empty tracked diff, be copied.
   • For a brief-check finding, <commit> is HEAD and nothing is applied, since the brief and its report are read as they stand on disk.
   • For premise, <commit> is HEAD and nothing is applied, since the step has no worktree and no diff.
   • Before the copy of a reviewer's finding is made, the output of git status --short and of git diff --binary <base> | shasum, run from inside the step's worktree, is written into the record.
   • A red command that would touch the user's real home, the installed skills or the pinned checkout runs with the variables that name those folders set to folders under $TMPDIR.
   • Done when the probes have a place to run and the record's section names it, and for a reviewer's finding the record holds the two outputs.
4. Build the red command: one command that drives the code path of the symptom and goes red on the exact symptom.
   • A hypothesis formed, or code read to form one, before the command has been run red is an Anti-patterns row.
   • Code read for a part the red command does not catch, as the bullets below say, forms no hypothesis and is not that row.
   • The red command asserts every part of the exact symptom, both halves of a two-part symptom included, so that the shrink keeps what either part needs.
   • Its output shows the result of each part: a suite that stops at its first failed assertion is run as one command per part, joined so that every one runs, so a cut that changes one part is seen.
   • The record's Red command section lists each part of the reported symptom with whether the red command catches it.
   • A part is caught when its assertion is red on the red command's runs.
   • A part with no assertion, or with an assertion that is green on those runs, is not caught.
   • Once the red command is red on the parts it catches, read the code that would produce each part it does not catch, along the path it drives.
   • When the code produces the part on that path, the red command is changed to assert it where it happens.
   • The assertion is on an output line, an intermediate state or a check before the run ends, since the end state can be unchanged when the run undoes its own change.
   • The part is then red and asserted like the others.
   • A part is called not reproduced, in the record or the session's final message, only when the code read along that path does not produce it.
   • A part written as not reproduced carries the lines read and why they do not produce it.
   • A red command that asserts only that something ran is an Anti-patterns row.
   • The ways to build one are in "Ways to build a red command", in the order to try them.
   • A red command of the first way, a failing test of the code where the symptom occurs, may be the test of Steps 16, and the record says so.
   • Each of the three runs starts from the same state: the red command sets its state up itself, or each run gets a fresh scratch folder.
   • A symptom seen only sometimes gets a failure rate measured over a stated number of runs, raised by more runs, parallel runs or narrower timing until it is high enough to probe against.
   • A slow symptom gets a baseline first: the known-good version or the requirement measured over repeated runs with the mean and the spread, and red is a threshold stated from them.
   • A defect in text (a skill, a page, a rule or a brief whose instructions led to the wrong behaviour) has as its red the quoted text beside the line of a run or transcript that shows the wrong behaviour it led to.
   • A credential the red command needs is taken from the environment, never from a file into its command line or the record.
   • When no red command can be built by any of the ways, or the scratch copy cannot reproduce because the symptom needs the real environment or a credential the environment lacks, the skill writes each way tried, with what it gave, into the record's "No red command" section.
   • Run by a person, that ends in the stop "No red command" ("Stops").
   • With no person present, that is the cause not found (Steps 15).
   • For premise, a red command that is green on main's head shows a false premise: the step's text says a behaviour happens that does not happen.
     • The false premise goes to /spec, which handles it as its Steps 2 handles a false premise.
     • Run by a person outside a /spec run, the false premise is also written into the step's Step 0 and committed, as the premise bullets of Steps 20 say.
     • The diagnosis of that part ends there, after Steps 21 and 22.
   • Done when the "No red command" section is written, or for premise the false premise is handed to /spec, or the command, as changed for a part it did not catch, has been run and its output quoted in the record, with the same result on three runs in a row or the measured failure rate for a symptom seen only sometimes, and the record lists each part of the symptom with whether the command catches it and the lines read for each part it does not catch.
5. Tighten the red command.
   • It gets a faster setup, a sharper assertion on the symptom, pinned time, fixed random seeds, the file system isolated under $TMPDIR and the network cut, as far as the symptom allows.
   • Done when it runs unattended in seconds where the symptom allows, and its runs after the tightening are quoted.
6. Shrink the case: cut each part of it (an input, a caller, a configuration value, a piece of data, a stage of the run) one at a time, running the red command after each cut and putting back a cut that turns it green.
   • Done when removing any remaining part turns the red command green, and the record's Shrunk case section lists each cut with its result.
7. Form three to five ranked hypotheses, each written as "If <cause>, then <change> turns the red command green" and naming the result that would falsify it.
   • Where it helps, a hypothesis adds "<another change> makes it worse".
   • A hypothesis whose falsifying result cannot be named is sharpened or dropped.
   • A hypothesis the shrink has already falsified is not one of the three to five.
   • The rank is by how much of the evidence (the red output, the shrunk case, the code read) each hypothesis explains, then by how cheap its probe is.
   • When the shrink and the code leave fewer than three causes standing, the list holds those, with the reason no other is live, and is never filled with one already falsified.
   • Done when the record's Hypotheses section holds three to five hypotheses in rank order, or fewer with the reason, each with its falsifying result.
8. Show the red command, its output, the shrunk case and the hypotheses.
   • Run by a person, the skill shows them to the user.
   • With no person present, the skill writes the hypotheses into the record and goes on to Steps 11.
   • With no person present, Steps 9 and 10 are not run.
   • Done when the user has been shown them, or with no person present when the record holds them.
9. Run by a person, wait for the user's reply before the first probe ("Stops").
   • Done when the user's reply is in.
10. Rank, drop or add hypotheses as the reply says.
    • Done when the record's Hypotheses section holds the list the reply leaves, with the reply quoted.
11. Make the one change of a probe: pick the next hypothesis in rank order and change one thing.
    • Two changes in one probe is an Anti-patterns row.
    • A probe tied to no hypothesis is an Anti-patterns row.
    • A debugger or an interactive session is used where the language has one, and otherwise logging at the boundaries that separate the hypotheses.
    • A hypothesis a debugger or logging probe leaves standing gets one more probe, the change the hypothesis names, so that Steps 15 has the red command green with it and red without it.
    • For a slow symptom, a probe is a measurement: a timing harness or a profiler at the boundaries, compared with the baseline of Steps 4, or git bisect run between two known states.
      • A log line does not measure time.
    • Every line of logging a probe adds carries one tag unique to the diagnosis, DIAG- and four hexadecimal digits.
    • Logging without that tag is an Anti-patterns row.
    • Logging everything to search afterwards is an Anti-patterns row.
    • Steps 11 to 13 repeat for each hypothesis until each has a result.
    • Done when the tree differs from what it was before the probe by that one change.
12. Run the red command after the probe.
    • Record the probe: the record's Probes section holds the hypothesis's rank, the one change as a diff, the run and the result, falsified or still standing.
    • A probe that breaks an other input, as Steps 15 says, leaves its hypothesis still standing, and the row names that input.
    • Done when the row is written.
13. Undo the change of the probe, the one that turned the red command green included.
    • Done when the tree is as it was before the probe, and the change stands in the record as a diff.
14. When every hypothesis is falsified, form a second list from what the probes showed.
    • Show the second list as Steps 8 says.
    • Run by a person, the skill waits for the reply and re-ranks as Steps 9 and 10 say before the first probe of the second list.
    • Done when the record holds the second list with its falsifying results, Steps 9 and 10 have run over it when run by a person, and Steps 11 to 13 have run over it.
15. State the cause: the hypothesis the probes left standing, with the probe that shows it, the red command green with the change and red without it.
    • The cause is stated at the operation that goes wrong: the comparison, the lookup, the write or the parse that gives the wrong result.
    • The operation is given with its place (the file and line, or the section of a text) and the rule it breaks.
    • The rule is stated at the kind of value the operation reads: how a value of that kind must be read or treated.
    • For a path, the rule reads "a path is read as the folder it names, whatever its spelling".
    • A rule that states only what the one operation does, such as "two spellings compare equal", is restated at the kind of value.
    • A cause stated as a property of the reported input, such as "the path has two trailing slashes", is not stated at the operation.
      • It is restated at the operation that treats that input wrongly.
    • When more than one hypothesis is left standing, the cause is the one that names what the operation gets wrong for every form of its input.
      • A hypothesis that names how the operation treats one form of a value, such as one spelling, is set aside for the cause.
    • A hypothesis whose probe broke an other input is not falsified by that input.
      • The probe broke the input when, with the probe's change, the red command went wrong on that input or stopped at it in its setup before the reported input was reached.
      • The broken input is recorded as an other input, in the probe's row of the Probes section.
      • The hypothesis gets one more probe in the form of Steps 12: its change made at the operation so that it also gives that input its right result.
      • That probe's change is undone as Steps 13 says.
    • With the cause stated, find every place of the defect.
    • A place is any operation that reads a value of the kind the rule is about and breaks the rule, whether a comparison, a derivation, a lookup, a write or a parse.
    • The operation the cause names is the first place.
    • The record names each further place with its file and line, or its section for a defect in text, and how it breaks the rule.
    • Search the code the red command drives and the code that feeds it.
    • Read forward from every source where a value of the kind the rule is about is read or assembled to every operation that uses it.
    • Every source counts: each environment variable, configuration entry and default that supplies such a value.
    • When the cause's rule is about the values a container holds, an operation that breaks only a rule of the container, such as how a list is divided into values, is not a place of the defect.
    • When the cause's rule is the container's own rule, every operation that breaks it is a place of the defect.
    • With the places found, list each other input that reaches a place of the defect:
      • another spelling of the same value: repeated or trailing separators, . parts, letter case, an encoding;
      • another name for the same thing: a link, an alias;
      • a value not yet there: a path not yet made, an empty value;
      • each other input the code that feeds a place of the defect admits.
    • Find them by reading the code or text that produces the inputs of each place of the defect, from the shrunk case back to where the inputs come from.
    • The list holds the inputs the code admits.
    • The reported input is not on the list.
    • Each other input's right result is written in the record before its runs.
    • The right result is the one the cause's rule gives, at whichever place of the defect the input is read.
    • For a defect in code, run each other input through the red command, with that input in place of the reported one and the assertion set to that input's right result.
    • The run observes the input's result at each place of the defect it reaches.
    • Run it on the tree without the fix and on the tree with the change of the probe that shows the cause.
    • Undo that change as Steps 13 says.
    • Record each result, right or wrong against the input's right result.
    • Put each other input in one of three classes, named in the record as written here:
      • part of the defect: wrong on the tree without the fix at a place of the defect;
      • not part of the defect: right on the tree without the fix;
      • another defect: wrong on the tree without the fix only at an operation that breaks another rule.
    • An input wrong at a place of the defect and at an operation of another rule is part of the defect.
    • The record names that input's wrongness at the other operation as another defect.
    • An input that is part of the defect is wrong at a place of the defect, so its failure costs something whenever the reported input's failure does.
    • An input of another defect is written in the record with its result.
    • An input of another defect is left for a diagnosis of its own.
    • For a defect in text, the operation is the instruction that led to the wrong behaviour.
    • For a defect in text, the kind of value is the kind of situation the instruction governs.
    • For a defect in text, a further place is another instruction of the same text that governs a situation of that kind against the same rule.
    • For a defect in text, the other inputs are the other situations that the instruction and each further place govern.
      • Each is read against the text in place of a run, and put in the same three classes.
    • Write the operation, the rule stated at the kind of value, each place of the defect, the list, each right result and each result into the record's "Operation and other inputs" section.
    • State the cause in the record's Cause section with that rule and each place of the defect.
    • The cause is not found when the second list is falsified too, when no probe can separate the hypotheses left, or, with no person present, when no red command can be built or the redacted output is not enough to diagnose.
    • For a cause not found, the record says so in its Cause section, with every probe or, when no red command could be built, a pointer to its "No red command" section, which lists every way tried.
    • Inside a plan, for every form but premise, a cause not found is raised to the user as an open item, the one plan-orchestration's "Stops" row "A finding that is the user's" leaves.
    • That open item quotes the hypotheses and every probe, or every way tried from the record's "No red command" section, and names the record's path.
    • A cause not found is never sent to the builder.
    • For premise, when the step's text has no other part, the open item is raised as the spec stop "A cause not found" ("Stops") shows it.
    • For premise, when the step's text has another part, the open item is raised as plan-orchestration's "Stops" row "A finding that is the user's" leaves it.
    • For premise, the open item quotes the hypotheses and every probe, or every way tried, and names the record's path, as for every other form.
    • For premise, that open item is the one open item for the part, and spec's Steps 2 raises no second one.
    • For premise run by a person outside a /spec run, the cause not found is also written into the step's Step 0 and committed, as the premise bullets of Steps 20 say.
    • With no person present outside a plan, a cause not found is stated in the session's final message with the record's path.
    • After a cause not found the skill goes to Steps 21 and 22, then inside a plan to Steps 23.
    • After a cause not found outside a plan, Steps 23 and 24 are not run, so the record stays in $TMPDIR and its path is shown.
    • Run by a person, a cause not found ends in a stop after Steps 22 ("Stops").
    • Done when the record's Cause section names the cause at its operation with the rule stated at the kind of value, each place of the defect and its probe, and the "Operation and other inputs" section holds each place and each other input with its class and its results before the fix, or the Cause section says "cause not found".
16. For a defect in code whose failure costs something, write a test that reproduces the shrunk case and reaches each place of the defect.
    • The test has one test case for the shrunk case and one for each other input that is part of the defect.
    • One of those test cases reaches each place of the defect and asserts the right result there.
    • Each test case asserts its input's right result, whether or not the change of the probe already gave it, so a later fix that narrows again goes red.
    • The rules file's rule that a test exists only for behaviour whose failure costs something decides whether the failure costs something, and with no rules file "Rules" decides it.
    • A defect in code whose failure costs nothing gets no test, and the record says so.
    • A place of the defect no test can reach is written in the record under "No test reaches it", with the reason.
    • A defect in text is fixed by reading, with the text quoted before and after and no test.
    • Done when the test is written with its test cases, each place of the defect reached by one, or the record holds the reason no test is written.
17. Run the test on the tree without the fix and quote its failure for each test case.
    • The tree is the one Steps 13 left, with every probe's change undone.
    • A test written after the fix is an Anti-patterns row.
    • Done when the record quotes, for each test case, a failure that shows the symptom, or, for a defect in text, quotes the text before.
18. Make the fix at the places of the defect, starting from the change of the probe that shows the cause.
    • The fix covers the operation the cause names and each further place.
    • Where the places can share one change, the fix is that change: a helper every place calls, or one written form made at every source the values come from.
    • Otherwise the fix is one change at each place.
    • The fix covers every source a value of the kind the rule is about comes from.
    • The fix at a place is one change, right for the reported input and for every other input that is part of the defect there.
    • The fix is never one change per spelling.
    • A fix that leaves a place of the defect giving a wrong result is not done, apart from a place written as not fixed.
    • Every input not part of the defect gives its right result, as it did on the tree without the fix.
    • An input of another defect is left out of the result.
    • The fix is not widened to make an input of another defect right.
    • When the change of the probe leaves an input that is part of the defect wrong, or makes an input that was right wrong, the fix is changed once more.
    • A place found only after the fix is made goes back through Steps 15 to 17.
    • On the way back, the runs of Steps 15 and 17 are on the tree as the first change left it.
    • The undoing of Steps 13 does not apply to the fix.
    • The failure of the new place's test case on that tree is quoted in the record.
    • The second change may widen the fix to that place.
    • After the second change, every input not part of the defect still gives its right result.
    • An input that is part of the defect and still wrong after that second change is written in the record as not fixed, with its result.
    • A place of the defect still giving a wrong result after the second change is written in the record as not fixed, with each input wrong there and its result.
    • The test case of an input not fixed is taken out of the test, so the test asserts no known defect.
    • The failing run of that test case is quoted in the record.
    • The Cause section and the session's final message name each input not fixed and each place not fixed.
    • A guard for a fix is an Anti-patterns row.
    • Done when the fix is in the tree the probes ran in and no place of the defect gives a wrong result, apart from a place written as not fixed, and the record quotes the fix, with each input and each place not fixed written in the record, or for a defect in text quotes the text after.
19. Run the test, the red command, the original, unshrunk case and the red command on every other input listed.
    • Each input that is part of the defect gives its right result at each place where it was wrong, except an input written as not fixed.
    • Each input not part of the defect gives its right result, as it did on the tree without the fix.
    • Each input of another defect is left out of the result.
    • For a defect in text, each place and each other situation is read again against the text after the fix and quoted in place of a run.
    • Done when the test is green, the red command is green, the original case is green and each other input gives the result its class requires at every place of the defect, each quoted in the record, with an input written as not fixed quoted with its result.
20. Inside a plan, hand the fix over by where the defect was found.
    • For a finding and a red line, the step's worktree is left unchanged, as "Rules" says.
    • A finding of the reviewer's first run of a full step: its fix and its test are the ruling of the next repair round, as plan-orchestration's Steps 8 sends a round.
      • The ruling quotes the hypotheses with their results, the cause, the fix, both runs of the test and the record's path.
      • The red command is the round's check.
    • A finding of a small text step's review is never sent to the builder, as the refute skill's "Finding dispositions" says.
      • Its fix is made at landing on main when it is small and inside the brief, and otherwise raised to the user as an open item.
    • A finding of the run over the last repair round: its fix is made at landing on main when it is small and inside the brief, and otherwise raised to the user as an open item, as the refute skill's "Over a repair round" 7 says, and it is never sent to the builder.
    • A red line: the step is already out of main (landing: backed-out), so the cause, the fix and the record's path are written in the step's Step 0 in plan.md, for /spec to carry into the step's new brief.
      • The fix is never made on main outside a landing, and never sent to the builder.
    • A brief-check finding: its fix goes into the brief, as the spec skill's "Steps / The brief check" 4 closes a finding.
    • premise: the cause, the fix, the red command and the record's path are written in the step's Step 0 in plan.md, for /spec to carry into the brief.
      • The fix is never made on main, since the step's builder makes it from the brief.
      • Run by a person outside a /spec run, every ending of a premise diagnosis writes its result into the step's Step 0: the cause and its fix, the cause not found with its open item, or the false premise with the red command's green output.
      • The session then commits the record, plan.md and, for a cause not found, the state file at once, as a resume point.
      • It stages them with git add -- <path> ..., since the record is a new file, then commits them with git commit -q -m "<message>" -- <path> ....
      • A /spec in another session then finds no uncommitted change on plan.md or the state file, which its Steps 1 would refuse.
      • Under /spec the record and Step 0 are the session's own records, which spec's preparation commit carries.
    • Done when the fix and its test stand in the place the defect's source names, and for a reviewer's finding git status --short and git diff --binary <base> | shasum from inside the step's worktree print what the record holds, and for premise Step 0 holds the result of the ending, as the premise bullets above say.
21. Run by a person, show the record whole to the user, before the cleanup.
    • With no person present outside a plan, the record's path is named in the session's final message instead.
    • With no person present outside a plan, Steps 24 is not run, so the record stays for whoever reads the run.
    • Done when the user has been shown the record, or the final message names its path.
22. Clean up, keeping the record.
    • Done when the grep of the tag over the tree the probes ran in prints nothing, and the scratch copy, removed with git worktree remove --force "$tmp/tree" from the main checkout, and every throwaway file are gone, a credential or .env file copied into $TMPDIR among them.
    • Run by a person outside a plan, done also when the red command run again on the original case is green.
23. Write where the cause is kept.
    • Outside a plan, the session drafts the last bullet of the commit message, which states the cause, the red command and the fix's test, and names "No test reaches it" with its reason when the record holds one.
    • Outside a plan, the session commits only as the repository's commit rule allows, naming the paths the fix changed in the form Steps 20 states, and otherwise shows the bullet to the user.
    • Inside a plan, the orchestrator books the record at the step's landing, as the land skill's Steps 9 says.
    • Done when the bullet is drafted and shown or committed, or, inside a plan, when the record's path and the cause are written for the landing's booking.
24. Outside a plan, run by a person, remove the copy of the record in $TMPDIR once it has been shown.
    • Done when the copy is gone.

Ways to build a red command

1. A failing test at the level that reaches the defect.
2. A command-line run on a fixture, its output compared with the expected output.
3. An HTTP request against a running server.
4. A headless-browser script that drives the view and asserts on what it shows.
5. Scratch files or a scratch repository under $TMPDIR that reproduce the state.
6. A replay of a captured input.
7. A small harness that calls the code path directly.
8. A loop over generated inputs, for a symptom that is sometimes wrong.
9. git bisect run on a scratch clone, when the defect appeared between two known states.
10. The same input through two versions, with the outputs compared.
11. For a symptom only a person can trigger, a list of actions for the user to take, which is the stop "A red command a person drives".
    • The session writes the list into the record, one action per line, each with what to look at after it, and shows it to the user.
    • The user takes the actions in order and answers each with one line that says what they observed, and a longer output the user saves to a file that the line names.
    • The record states which observation is the red before the user takes the actions.
    • Each run of the red command that the steps ask for is one pass through the list.
    • The session quotes each run's actions with the user's observations whole in the record's "Red command" section before the cleanup of Steps 22, a secret in them written <REDACTED>.
      • The observations are the red command's own output, not a captured artifact, which "Rules" quotes only in the lines that carry the symptom.

Stops

The first five rows are stops. The cause not found, inside a plan, is a decision for the user and leaves an open item, and the other stops leave none. The last five rows are refusals.

• After the refusal "No dispatch entry" for a finding of a reviewer's report, the step is prepared with /spec, then /diagnose runs again.
• After the refusal "No dispatch entry" for a red line, /diagnose runs again once /land has taken the step back out of main and before /spec prepares it again.
• After /spec has prepared a red line's step again, /diagnose <symptom> runs with the failure in the step's Step 0 as the symptom.
• After the refusal "No dispatch entry" for a step already landed, /diagnose <symptom> runs with the finding's failure scenario as the symptom.

Anti-patterns

Rules

• Who is present decides the waits: a person running the skill, by hand or inside a plan they run step by step, gets the waits of "Stops", and a session with no person present, a diagnosis agent or one running /diagnose <symptom> on its own, gets none.
• Inside a plan with no person present, the skill runs in a fresh agent, the diagnosis agent, for every form: <finding> and round <n>, red line, brief check <n> and premise.
  • Run by a person, the skill stays in the person's session.
• The session that holds the skill, the orchestrator or the /spec session, starts the diagnosis agent.
  • It starts the agent as the effort agent ordo-<reviewer_effort> on the model the configuration block's reviewer: names, and checks it as the refute skill's Steps 1 checks its reviewer:
    • The runner lists the effort agent.
    • CLAUDE_CODE_EFFORT_LEVEL is unset.
    • The session reads the agent's id and served model right after the start.
    • A served model that is not the configured one is the stop "A model other than the configured one".
      • The agent is stopped.
      • Nothing it wrote is used.
• The session makes the refusals of Steps 1 before it starts the diagnosis agent.
• The diagnosis agent changes no file of the main checkout or of the step's worktree.
• The diagnosis agent starts no agent and invokes no skill other than reading this skill's text. Every read and every probe of the diagnosis runs in the diagnosis agent's own session.
• The diagnosis agent's probes run on the scratch copy of Steps 3.
• The diagnosis agent's final message is the diagnosis record whole, which the session saves at agents/reviews/<step>-diagnosis.md, under its own heading below an earlier diagnosis of the step.
• The session, not the diagnosis agent, raises a cause not found as Steps 15 says.
• The session, not the diagnosis agent, writes what Steps 20 says into the step's Step 0 for red line and premise.
• Right after the diagnosis agent's start, the session writes the agent's numbered item into plan.md's Agents section.
  • The item reads <n>. <agent id>: diagnosis of step <k>, <served model>.
  • It stands under the heading "Agents in no role the cost script prices:", which the session makes when the section has none.
  • An agent stopped for another model is written <n>. <agent id>: diagnosis of step <k>, <served model>, stopped.
• The record's head holds the agent's id, its served model, and its tokens, tool uses and time from its completion notice, which the session fills.
• Inside a plan, the step's worktree, when the step has one, is never changed and every probe runs on the scratch copy of Steps 3, so plan-orchestration's rule that a finding whose cause is not known is diagnosed read-only holds.
• The skill runs against the user's real home, the installed skills or the pinned checkout only with the user's leave.
• A red command that would touch the user's real home, the installed skills or the pinned checkout runs with those paths redirected, as Steps 3 says.
• Every quoted command output carries <REDACTED> in place of the value of a secret in it (a password, an API key, an access token, a private key, a session cookie, a credential inside a URL or a connection string), and keeps the rest of the line as printed, as the rules file's rule on secrets in quoted command output says.
• A captured artifact is quoted only in the lines that carry the symptom.
• A statement about what the code does, such as "the cache is cleared only on restart", goes in the record and the final message only with the lines it rests on, read in this run.
• With no rules file, a defect in code whose failure costs something (lost work, a broken installation, a wrong configuration accepted) begins with a test that fails on the tree as it is.
• With no rules file, a guard is not a fix: a null check, an early return or a fallback does not close a defect.
• With no rules file, the fix reaches the code that lacks the thing it needs.