Resolve a problem report

A report is not a bug and it is not a specification. It is somebody's account of a thing that
surprised them, written in their words, usually with a cause already attached and often with
numbers in it. Resolve the account and you have fixed whatever the reporter guessed. Resolving
the report means finding out which parts of it are true first — and being willing to come
back with "two of these three hold, and the third names a thing that does not exist."

The expensive failures here are quiet ones. The described symptom gets patched while the cause
stays. The cause is asserted from a code reading when the claim was about production. The
reporter's numbers travel into the resolution note unchecked. Three candidates are offered and
all three propose doing something, because "this was fixed three weeks ago" is not a satisfying
thing to say out loud. And the close rests on a green suite that never covered the surface.

Six gates. Each ends in a named artifact, and each one refuses to open until that artifact
exists — not until it looks convincing. The gates run in order, the middle ones delegate to
companions that own the work, and the pipeline can correctly terminate at any of them: a
question is an outcome, and so is a refutation with no action.

Six gates, six artifacts

A gate that cannot open is information: the artifact under it is missing, which is far better
said at G1 than discovered at G5, with a change landed and somebody waiting for a mail.

What this skill does not own

investigate-codebase owns G1's searching, and this skill inherits its complexity rubric,
control rule and contradiction table rather than restating them. blast-area is called once
per candidate at G2 and again on every budget breach; visualise-blast-area draws its map when
candidates must be compared by someone who will not read a table. land-complex-change receives
the contract and the paths at G4 and returns the budget, the ladder and the change band — this
skill runs none of its own. describe-changes writes the resolution note from the landed diff at
G5; request-blocks-review and blocks run the review loop, given the contract, the budget, the
ladder and the residuals. new-ux-discovery hands in chosen candidates; no sweep happens here.
model-routing chooses models — this skill names roles and bands only; agent-lifecycle keeps
the child bookkeeping; derive-codebase-context builds the durable artifacts this one reads.

Install the companions with npx skills add crissmoldovan/agent-skills.

When to Use

• A bug report arrived with a cause already attached, and the cause is doing load-bearing work.
• A report quotes numbers — counts, durations, percentages — and the resolution will be judged
  against them.
• A feature request needs its implications worked out before anyone agrees to it.
• Two reports may be the same report, or the same report may be two.
• The obvious patch would fix the symptom described and leave the mechanism in place.
• A report has been open long enough that "is this still true?" is a real question.
• The last attempt at this one turned into a scope argument, because nobody wrote down what the
  chosen fix was not going to do.

Do not use it to answer a question about how the code works — that is investigate-codebase,
which this skill calls at G1 rather than improvising its own searching. Do not use it to map
what a change would hit; blast-area owns that, and this skill calls it per candidate. Do not
use it to build a change already decided with no report behind it — a roadmap item, a dependency
bump, a deprecation with a date — that is land-complex-change, which this skill delegates to at
G4 and which is not a superset of this one, in either direction: a report can correctly end
with no change at all, a change frequently starts with no report, and manufacturing one to feed a
pipeline produces intake artifacts that are fiction. Do not use it to describe a change that
already landed — describe-changes reads the diff — or to run the review loop over a pull
request, which is request-blocks-review and blocks. Do not use it to go looking for
improvements nobody has filed; new-ux-discovery sweeps for those and hands the chosen ones
here. And do not use it as ticket hygiene: a pipeline that always produces a change will produce
one for the report whose correct answer was a question.

Prerequisites

1. The report in its original words, with its numbers intact. Not a summary: the phrasing
   carries which surface they were on and what they expected, and paraphrase silently repairs
   the false premise you most needed to see.
   Complete when: the text, its date, the reporter's role and every number in it are in hand
   — or their absence is recorded.
2. A readable checkout at a named revision. The sha, and whether the tree is dirty. A cause
   measured against uncommitted work describes a state nobody else has.
   Complete when: revision and dirty state are recorded.
3. The reach needed to reproduce, declared before reproducing. A claim about production
   needs production observation; a computed value needs the computation run; behaviour on a
   surface needs that surface reachable. Some of it will not be reachable from here.
   Complete when: each claim is marked reproducible here, reproducible only with access you
   do not have, or not reproducible at all — with the reason.
4. The reporter reachable, or explicitly not. Reports stall for one sentence from the
   person who filed them.
   Complete when: the channel is known, or the run is marked unreachable and every falsifier
   can be checked without them.
5. The repository's own checks located and runnable here. Test command, typecheck, lint,
   build, and any manual step that constitutes a check.
   Complete when: each is named with the command that runs it, and at least one has been run
   in this checkout to prove the apparatus works.
6. Every irreversible act this resolution could reach, enumerated. A migration, a
   production write, a deletion nothing restores, closing the report, any outbound message
   to the reporter — the last two get forgotten for being cheap to perform and impossible to
   retract.
   Complete when: the list exists — or is empty and says so.
7. Attendance declared, conservatively. If you cannot confirm a human will see and answer a
   question in this run it is unattended, which changes the act policy and the run record.
   Complete when: the run is marked attended or unattended before G0.

Procedure

1. Score the band before spending anything, and announce it on one code path. The rubric
   belongs to investigate-codebase: run that one, do not restate it and do not invent a
   second. Two things are this skill's own: a report whose resolution ends in closing the
   report or mailing the reporter scores cost-of-being-wrong 2, which forces at least the
   normal band and arms the act gates in step 6; and the rubric is re-scored after G1, in
   either direction, because reproduction routinely moves the scope signal by an order of
   magnitude. Announce band, signal scores with their observables, any override and the caps it
   buys — before the first child is dispatched, watched or not. Never ask which mode to run.

2. G0 — restate the report as a claim that could be false, and write its falsifier. One
   sentence, nouns resolved to things you can point at, next to one sentence saying what
   observation would prove it wrong. "Exports are broken" is not a claim; "the export endpoint
   returns rows for one account and none for another, for the same query" is, and its falsifier
   is a run of both. Classify the report as bug, feature, or question — they need
   different evidence at G1 — and record the premises separately from the claim, because a
   report usually asserts a cause as well as a symptom and those two are falsified by different
   observations. Partial refutation is normal and is not an accusation: accept the premises that
   hold, reject the one that does not, and reject it with a number. The card's fields and the
   worked restatements are in the gate contracts.

   Enumerate the readings from the requirement's own words. The ambiguity that stops a build
   lives in the wording a builder will be held to — not in the failure symptom, which is one
   thing that went wrong once. Read the requirement clause by clause, list every reading its own
   words admit, and cost each one; where two imply different work and no bounded probe
   separates them, that is the blocking question, and it blocks G3 rather than being settled by
   whoever writes the contract.

   Cannot proceed until: the claim is falsifiable, the falsifier is checkable with the reach
   declared in prerequisite 3, the report's asserted cause is written as a premise rather than
   absorbed into the claim, and the readings its own words admit are enumerated and costed.

3. G1 — analyse, at the class the claim requires, and reproduce every number. Delegate the
   searching to investigate-codebase: it owns the decomposition axes, the child result
   contract, the control rule (a zero-hit search is "absent" only when a control fired) and the
   contradiction table. This gate adds two requirements of its own.

   The evidence class is set by the claim, not by what is convenient. The ranking —
   production observation > deterministic local measurement > code reading > docs, comments and
   PR titles > recollection — decides ties, and reach decides admissibility: a production
   observation from a surface the report was not about proves nothing about the report. A claim
   that something happens is not settled by a code reading that says it should. Where the
   required class is out of reach, say so and mark every downstream claim as resting on a lower
   class; do not quietly promote a code reading into an observation.

   Reproduce the numbers — all of them, one row each.

   number as reported | what it measured | measured here | delta | verdict

   Verdicts from a closed set: reproduced, diverged, not reproducible (needs X),
   inconclusive. A partial reproduction is a finding, not a failure. In one measured case
   six of nine reported figures reproduced exactly and three did not — and the three were the
   answer, because they shared a property the six did not and that property was the mechanism.
   An agent that reports "could not reproduce" over that table has thrown the result away. And
   date everything inherited: a report is an account of a past state, so every claim carried
   from it answers "was it true?" only. Resolve each at the current revision and record it as
   true at <sha>, not true at HEAD where it has stopped holding — frequently the entire
   resolution. Class rules, the table worked through, and unreproducible claims are in
   reproducing the claim.

   THE SEPARATE-DIAGNOSIS RULE: reproducing every number does not test the cause. A number is
   evidence for a mechanism, not the mechanism, and the two carry independent truth values. So
   add a row per causal claim and make its test a falsification — name what must be true if
   the mechanism holds, then look for its absence. Where the verdicts disagree the symptom is
   still real: confirm the observation, refute the mechanism, carry the corrected cause into G2.
   This catches the competent reporter, and a build against a wrong cause is frequently
   destructive while looking exactly like a correct one — three measured cases, the shape of the
   test and its weight at G2 are in falsifying the diagnosis.

   Decompose every limit before arguing about it. Where the report or the requirement cites
   a size, a duration, a count or a quota, measure what the number is made of — each
   contributor, its share, and whether the change would move it — before reasoning about
   remedies. An infeasibility claim built on an aggregate is an over-claim. In one measured
   case a payload declared too large for its limit was dominated by a single field nothing
   downstream read; removing it fitted the limit with room to spare, against a redesign that was
   already on the table.

   Cannot proceed until: the cause (bug) or the implications (feature) are stated at the
   required class with path:line at a sha behind them; every reported number has a verdict;
   every cited limit is decomposed into its contributors; every load-bearing negative names a
   control that fired; and every inherited claim is dated.

4. G2 — offer 2–4 candidates, and make the honest ones real candidates. Call blast-area
   once per candidate — comparing fixes by what each disturbs is the entire point of the
   gate, and it is the comparison that a list of approaches cannot make. Every candidate carries
   five fields: its blast area (surfaces, break times, deploy ordering), what it does not
   fix, reversibility (what a revert restores and what it does not), size, and the
   evidence it rests on. Four candidate classes must be considered every time, and included
   whenever they survive contact with G1:

   • Already fixed, or retracted. The behaviour changed at some revision after the report
     was written, or the premise the report rested on is gone. This is a result, and the work
     is dating the claim, not building anything.
   • Do nothing, deliberately. With what the report costs if left, and what would make it
     worth revisiting. A pipeline that cannot output this will output a change for every report
     it is handed.
   • The precedent this repository already used. The same problem, solved elsewhere in the
     tree, possibly under another word. Search for it before inventing a fourth approach: an
     existing solution costs less to review and maintain, and its blast area is already known.
   • The sibling requirement already in the ticket. When the requirement that stalled is
     ambiguous or blocked on a limit, the better-specified one beside it frequently delivers most
     of the value at a fraction of the cost. It is a real candidate carrying the same five fields
     — ranked in the table, chosen by the reporter or the owner, and stating what it does not
     fix — never a consolation prize produced once the first one fails.

   Rank by consequence, not by elegance, and say which one you would take and why in one
   sentence. Then apply step 6: above the light band the choice is the reporter's or the owner's,
   not yours. Candidate rules, the comparison columns and a worked offer are in
   candidate offers.

   Cannot proceed until: at least two candidates exist with all five fields filled; the
   already-fixed, do-nothing and sibling-requirement lines have each been evaluated and are
   present or explicitly dismissed with a reason; each candidate's blast area came from the
   mapping skill or names the reason it could not; and the chosen candidate is recorded with who
   chose it.

5. G3 — write the build contract, and make every requirement provable. The spec is not
   prose about an approach; it is a contract a builder can be held to and a reviewer can check
   line by line. One template:

   BUILD CONTRACT  <report handle>  base <sha>  band <light|normal|deep>  candidate <chosen>
   
   R1  <one checkable requirement, in one sentence>
       FILES     <the paths this requirement owns — disjoint from every other requirement>
       PROVES    <the test that proves it: path + test name>
       MUTATION  <the edit to the implementation that must make that test fail>
       OUT       <what this requirement explicitly does not do>
   
   R2  …
   
   MUTATIONS   Every test named above is watched failing under its own mutation before the
               implementation lands. A test that has never been observed failing is a claim.
   NOT IN SCOPE  <the candidates that lost, and what each would have fixed>
   STANDING INSTRUCTION  Report brief errors instead of implementing them. If a requirement
               contradicts the code, another requirement, or itself, stop and return the
               contradiction with its evidence. Do not implement around it, and do not pick
               the reading that is easiest to build.

   Disjoint file sets are what make requirements independently revertible and reviewable;
   where two genuinely need the same file, say so and sequence them. The mutation line is the
   load-bearing one. In one measured repository four CI guards were added that had never been
   capable of failing — each passed from the day it landed and each was reported as coverage. In
   another, a swallow-by-design path made its own test decorative: it asserted that nothing
   threw, which the code guaranteed. A mutation costs a minute and converts both into evidence.
   Template, disjointness, mutation forms and a worked contract are in
   the build contract.

   Cannot proceed until: every requirement has files, a proving test and a mutation; the
   file sets are disjoint or the overlap is declared and sequenced; the losing candidates appear
   under NOT IN SCOPE; and the standing instruction is in the text the builder actually receives.

6. Confirm by the two-column rule — and confirm at the act, never at the plan. The default
   is read off two columns, and either one turning it on is enough:

   Column	What it reads	Confirmation at G2
   Cost of being wrong	the rubric's fifth signal scored 2 — the resolution authorises a migration, a deletion, a production write, an outbound message, or closing the report	default ON
   Reversibility spread	the candidates differ in what a revert would restore	default ON
   neither	a light-band report whose candidates are equally revertible	default OFF, with a one-line notice naming the candidate taken and how to undo it

   Default-off is deliberate: a pipeline that stops to ask about every typo in help text stops
   being run. Above that line one confirmation at G2 — the candidate, not the implementation —
   carries the rest of the pipeline.

   Separately and always: any irreversible act is confirmed at the moment of the act, with
   four things stated — what is about to happen, what it touches, what it cannot undo, and what
   happens if it is not done — and then a wait. Closing the report and mailing the reporter are
   irreversible acts; they feel like paperwork and they reach a person. An unattended run
   takes no irreversible act at all: it stops, leaves the work staged, and reports exactly
   what remains. The full policy, the notice wording and the degradations are in
   the confirmation policy.

7. G4 — hand the build to land-complex-change, with the contract and the paths and nothing
   else. That skill owns the landing half and returns three artifacts this one does not build:
   the side-effect budget (the touch-set declared from the blast map, with its out-of-bounds
   classes and its on-breach rule), the regression gate ladder (one guard per affected
   surface, watched failing before and passing after, unguarded surfaces recorded visibly), and
   the change band with its act gates. Its breach rule applies here as written: work outside
   the budget stops, re-enters blast-area, and resolves to extend, split or abandon —
   never silent absorption. A breach that invalidates the chosen candidate returns to G2, not to
   the reporter as a surprise.

   Context is the contract plus the file paths — never the investigation transcript, which
   carries discarded hypotheses, refuted premises and the reporter's own diagnosis; a builder
   handed all of it will implement some of it. It belongs in the run record.

   Cannot proceed until: the budget and the ladder come back with the diff; every affected
   surface has a ladder row with its rung; every rung-1 guard has quoted fail-before evidence;
   and every breach is recorded with its disposition.

8. G5 — verify at the class, describe, review — and file what verification turns up.
   Verification is not the test suite going green; it is each numbered requirement checked at
   the evidence class its own claim requires, plus a re-measurement of the reporter's
   original numbers against the same table from G1. A green suite over a surface nothing guarded
   is evidence about the other surfaces.

   A verification that opens a new report is a success. When the re-measurement turns up a
   figure that disagrees with the system's own — two counts of the same thing differing by more
   than a hundred rows is the classic shape — file it as its own report and close this one on
   its own contract. Chased instead, in one measured case, the original stayed open for weeks
   and the new finding was never filed under its own name: two problems, invisible in one row.

   Hand the landed diff to describe-changes for the resolution note — its short register is
   the reporter's line, its detailed register is the reviewer's — and the pull request loop to
   request-blocks-review and blocks, giving them the contract, the budget, the ladder and
   the residuals alongside the diff. Then, behind step 6's act gate, close the report and tell
   the reporter what was true in their account, what was not, what changed, what it does not
   fix, and what to do if it recurs.

9. Deliver the outcome the evidence supports, including the ones with no change in them.
   Three terminal outcomes are legitimate and each is delivered with its evidence:

   • A resolution — a landed change with its contract, its gates and its residuals.
   • A question — the report needs one answer no bounded probe can settle, and the
     deliverable is that question with its established facts, the branches with their costs, and
     the default if nobody answers. Probe what a probe can settle; ask only the rest.
   • A refutation with no action — the premise does not hold, the thing was fixed already,
     or the requested action has no referent: one report asked for a nightly run of a pipeline
     with no runnable entry point, and the correct output was the refutation plus the two things
     that did exist. Resisting a wrong fact and resisting a wrong instruction are different
     behaviours — the second returns a decision brief and a question, not a completed action
     with a caveat attached.

10. Document the run when the branch calls for it. The convention is below, and it is
    identical in every skill of this family that supports it.

The run record

Documenting the run. Write a full record when the invocation carries --document (or
an unmistakable phrase such as "document the run"), at docs/resolve-problem-report/<UTC-date>-<slug>.md
in the host repository — and always when the run is unattended, in which case it goes to the
harness scratch directory, never the repository, and its path is named in the final answer;
if you cannot confirm a human will see and answer a question in THIS run, treat it as
unattended. Attended with no token: stay silent, offering once only if the run ends with an
unresolved contradiction or an open blocking question. Five headings, in order: What was
searched / Who searched it / What each found / How it reconciled / What was decided and why,
closing with what this run could not see. No secret values, machine-absolute paths, child
transcripts or raw logs; no unmarked inference or unearned benefit claims; never edit an
earlier record, and never let writing one change the answer.

Records are written per the run-record convention.

Usage Examples

Here is the report as it came in. Turn it into one sentence that could be false and keep the
cause they suggested separate from what they observed. When you reach options, include doing
nothing and check what the ticket already asks for before inventing a new approach.

They say the nightly total double-counts and they quote nine figures. Reproduce all nine before
you go near the code — and if only some come out right, the ones that did not are the answer.
Falsify the mechanism they proposed as its own claim while you are there.

Run this one unattended overnight and document the run (--document). Stop at anything you cannot
take back, and file any number that disagrees as its own report rather than holding this open.

Pitfalls

• Resolving the reporter's diagnosis instead of their report. The cause they attached is a
  premise, and the part most likely to be wrong: they saw a symptom and reasoned backwards.
• Answering at the wrong evidence class. A code reading that says the value should be
  written does not settle a report saying it is not there. Class breaks ties; reach decides
  whether the evidence was about this at all.
• The numbers nobody re-ran. They travel into the resolution note unchecked, and the note is
  believed because it has figures in it.
• Treating a partial reproduction as a failure to reproduce. Six of nine reproducing is the
  most informative result available: the three that did not are a filter on the mechanism.
• Infeasibility declared over an aggregate. "It will not fit" is a claim about every
  contributor at once, made without measuring one of them — and the dominant one is usually the
  one nothing downstream reads.
• The ambiguity located in the symptom. The words a builder is held to are the
  requirement's, and a reading nobody costed is one the builder resolves silently, in favour of
  whichever is cheapest to write.
• A stale claim built on. The report describes a past state; anything inherited from it
  answers "was it true?" and needs a current-state check before it becomes a requirement.
• Accurate numbers taken as a verified cause. The expensive miss is a careful report whose
  figures reproduce and whose mechanism does not, because nothing downstream reopens a question
  the table appeared to close — see falsifying the diagnosis.
• All candidates propose doing something. If "already fixed" and "do nothing" are never
  offered they were never considered, and the pipeline has an outcome it cannot reach. The
  fourth invented approach usually already exists in the tree under a different word, which is
  why searching for the precedent is a named step and not a hope.
• Candidates compared by description. Without a blast area each, the comparison is between
  two summaries and the more confident one wins.
• A contract whose file sets overlap. No requirement can then be reverted alone, review
  cannot attribute a defect, and the first regression rolls back all of them.
• A test that could never have failed. Green from the day it was written, reported as
  coverage. The mutation is a minute; skipping it is how a suite becomes decorative.
• Handing the builder the investigation transcript. It contains the refuted premises and the
  discarded approaches, and some of them will end up in the diff.
• Confirmation asked at the plan and not at the act. At plan time nothing irreversible is
  imminent and the person answering has no context; at act time they have both. Closing the
  report and mailing the reporter are two of those acts — cheap to perform, and no revert takes
  them back off a person's screen.
• Chasing the disagreement verification found. File it: holding this report open to chase
  it hides two problems in one row that reads as in-progress.
• Closing on a green suite. A suite passing over an unguarded surface is evidence about the
  surfaces it covers, not about the one the report was filed against.

Verification

• The band was scored with investigate-codebase's rubric (not a second, local one) and
  announced before any child was dispatched, with signal scores and the caps it buys.
• Cost-of-being-wrong was scored 2 where the resolution closes the report or messages
  the reporter, and the band floor and act gates followed from it.
• G0: the claim is one falsifiable sentence with its falsifier written down, the report
  is classified bug / feature / question, and the reporter's asserted cause is recorded as a
  premise, separately.
• G0: the readings the requirement's own words admit are enumerated and costed — not
  only the ones the failure symptom suggested — and any unresolved reading blocks G3.
• G1: the cause or implication is stated at the evidence class the claim requires, with
  path:line at a sha — or the required class is named as out of reach and the downstream
  claims are marked as resting on a lower one.
• G1: every number in the report has a row and a verdict from the closed set, and a
  partial reproduction is reported as a finding rather than as a failure.
• G1: every causal claim has its own row and its own falsification, and where the numbers
  reproduce but the mechanism does not, the corrected cause is what reaches G2.
• G1: every limit the report or the requirement cites was decomposed into its
  contributors before any remedy was argued, and no infeasibility claim rests on an
  aggregate nobody measured.
• G1: every inherited claim is dated to a revision, anything that stopped holding is
  recorded as true at one sha and not at HEAD, and every load-bearing negative names a
  control that fired.
• G2: 2–4 candidates carry blast area, what-it-does-not-fix, reversibility, size and
  evidence — each blast area from the mapping skill, or with the reason it could not be.
• G2: already-fixed, do-nothing and the sibling requirement already in the ticket
  were each evaluated, and the repository was searched for a precedent before a new approach
  was proposed.
• The choice is recorded with who made it, and the two-column rule decided whether it
  needed confirming.
• G3: every requirement names its files, its proving test and the mutation that must
  kill that test; the file sets are disjoint or the overlap is declared and sequenced.
• G3: the losing candidates appear under NOT IN SCOPE, the standing instruction to
  report brief errors instead of implementing them is in the text the builder received,
  and every proving test was watched failing under its own mutation before landing.
• G4: the build was handed to land-complex-change with the contract and the paths and
  not the investigation transcript, and it returned a budget and a gate ladder.
• Every budget breach stopped the work, re-entered blast-area, and resolved to extend,
  split or abandon — with any breach that invalidated the chosen candidate returning to G2.
• G5: each requirement was verified at its own evidence class, and the reporter's
  original numbers were re-measured against the G1 table.
• Every disagreement verification turned up was filed as its own report, and this one
  was closed on its own contract rather than held open to chase it.
• The resolution note came from describe-changes and the review loop from
  request-blocks-review, which received the contract, the budget, the ladder and the
  residuals alongside the diff.
• No irreversible act — migration apply, production write, deletion, report close, outbound
  message — was taken without consent at the act; none was taken in an unattended run.
• Where the outcome was a question or a refutation with no action, it was delivered
  with its evidence and its branches, and no change was manufactured to fill the gap.
• Where a record was written, it exists at
  docs/resolve-problem-report/<UTC-date>-<slug>.md (or the harness scratch path for an
  unattended run, named in the final answer), under the five required headings.

Deeper reading

Each file carries the detail its section summarises: the gates and their artifacts in
gate contracts; classes, the reproduction table and false premises
in reproducing the claim; the falsification test, its three
measured cases and its weight at G2 in falsifying the diagnosis;
the five fields, mandatory classes and precedent search in
candidate offers; the template, disjoint file sets and mutation
forms in the build contract; the two-column rule, act-gate script
and unattended stop in the confirmation policy; the five
headings and prohibitions in the run-record convention; and
one report end to end — partly reproduced, premise refuted, disagreement filed as its own report —
in a worked resolution.