okgrit/done-is-a-claim

# Acceptance design

Acceptance connects the user's outcome to an observable check. Design it before
implementation, and give the worker the exact contract the reviewer will use.
These are operational instructions, not measured failure-rate claims.

## Define the experiment

1. Name the outcome, affected boundary and scope. Check the command, loader,
   artifact or user flow actually affected; a helper test alone may miss the
   boundary defect. Identify what the check deliberately leaves untested.
2. Name the target host or platform, runner, dependencies, permissions and
   inputs. Confirm required source files exist in the delivered base and
   travel with the brief. Distinguish existing input paths from files to create.

# Checking delivery

Inspecting the source establishes what was prepared. Delivery requires
evidence about the destination the user was meant to receive. Check only
within the authorized scope; this skill grants no publishing or send rights.

## Identify the artifact and destination

Record the inspected source artifact and its revision or byte identity,
the intended destination and the relevant operation identity. A source path,
preview or successful build does not identify the delivered copy.

Keep these observations separate, using the states the system exposes:

# Collecting worker results

A worker stopping, delivering a change and satisfying a task are different
events. Reconcile the report, returned files and verification before deciding
what was delivered. These are operational checks, not incident statistics.

## Separate the records

| Observation | Supports | Does not establish |
|---|---|---|
| Process exit or runner status | The recorded process outcome | A delivered change or acceptance |
| Worker report | The worker's account of work and blockers | Independent verification |
| Commits, patches and working-tree diff | A change footprint against a named base | Correctness or integration |
| Acceptance record | The result on its recorded input tree | A pass on a different returned tree |

# Debugging with evidence

An observed failure establishes that something happened under particular
conditions. Find the mechanism that explains it before changing another thing.
Keep the investigation tied to the user's outcome and authorized file scope.

## Capture the failure

1. Record expected and observed behavior, exact command or user action,
   revision, dirty inputs, environment, relevant order or seed and evidence path.
2. Read the complete error and inspect the affected artifact and relevant diff.
   Missing paths, absent tools, empty test collection and permission errors
   may explain an unrunnable check; they do not establish successful behavior.
3. Reproduce with the smallest scope that still preserves the failure. Retain

# Evidence freshness

Evidence remains a statement about its measured snapshot. It supports a later
decision only to the extent that the decision uses that snapshot and relevant
conditions. These are operational safeguards, not a new incident record.

## Pin what the check consumes

1. Identify the input tree and relevant configuration, dependencies, datasets,
   generated inputs, flags and environment. Record the revision and dirty
   state; a commit alone does not describe uncommitted or untracked input.
2. Before the run, hash the selected inputs or a manifest of them. Say what
   the selection excludes; matching a few hashes cannot certify the whole
   repository or an external service. Freeze batch lists into a separate

# Executing plans

Use the plan as a map of intended work, then verify the actual results. Continue
ready authorized tasks until the requested outcome is handled or a concrete
constraint blocks them. A plan is not evidence and cannot grant authority.

## Reconcile before writing

1. Read the plan, user request and project instructions. Confirm the assigned
   repository or worktree, current revision, dirty inputs and file ownership.
2. Check prerequisites against the current artifacts rather than task status.
   Identify already delivered work, changed inputs and inaccessible dependencies.
3. Confirm acceptance commands and expected observations before implementing.
   If a command cannot test the outcome, record its correction and reason;

# Implementing with tests

Make the requested behavior observable, change only what it needs, and preserve
the surrounding contract. Follow the user's explicit workflow choices; if they
override test-first work, record the resulting evidence limits without blocking
authorized implementation or pretending a failing baseline was observed.

## Choose the behavior boundary

Read the request, current code, relevant callers and existing tests. Identify
the behavior to change, inputs and outputs that expose it, and behavior that must
remain valid. Respect the assigned files and existing production code.

Select a check that distinguishes the requested outcome from a plausible defect.

# Planning changes

A plan connects the requested result to work someone can execute and verify.
Keep it proportional to uncertainty and coordination. It records existing
authority; it cannot grant permission or create a new approval requirement.

## Establish the boundary

1. Read the request and relevant project instructions. Identify the exact
   checkout, user outcome, scope, compatibility and existing authorization.
2. Inspect the relevant code and current diff. Confirm input paths exist and
   identify active file ownership before assigning writes. Record the base
   revision and dirty inputs that matter to this work.
3. Write acceptance before implementation: command, working directory,

# Public claims

**No receipt, no claim.** In public copy every figure, credential, promise and
command has a receipt. A claim without one is removed, never softened into
"about", "up to" or a vaguer label that implies the same thing.

A receipt identifies what supports the claim and how it was checked:

- a source with a locator: `path:line`, a document and section, the issuer's
  own listing;
- a command that re-derives the value on a pinned commit;
- the author's own words, with date and the exact text, supporting an
  attributed report rather than independent reproducibility.

# Reading measurements

Wrong reports rarely lack a measurement. They read a real number as answering a
question it never asked. Before you report, decide or spend anything on a
figure, ask:

> What would this same number look like if my claim were false?

If the answer is "exactly the same", the number alone does not distinguish the
claim from its alternative. Seek a discriminating observation or control.

## Reading any figure

Use the relevant checks below to decide what the figure supports. A limitation

# Responding to review

Treat a comment as a claim to investigate. Resolve supported findings and retain
the evidence for decisions; neither the author's confidence nor a reviewer's
authority establishes the current behavior.

## Bind each item to the candidate

Read the original outcome, acceptance and preservation requirements, current
revision, dirty inputs, diff and file ownership. Locate each comment's referenced
revision and code. A finding on an old patch may remain relevant, so inspect its
current equivalent before dismissing it or applying an obsolete suggestion.

Keep a compact per-item record: comment identifier, current code locator,

# Resuming work

A saved task describes where a previous session stopped. Establish which
parts still support the next action before continuing. Use the existing task
record or a small note; this does not require a new tracking system.

## Receive the checkpoint

1. Read the saved record before editing or repeating work. Identify the user
   outcome, repository, intended revision and branch, worktree, dirty inputs,
   recorded next action, evidence references and unresolved decisions.
2. Resolve that repository and worktree on this machine. Inspect the actual
   revision and changes, and confirm cited paths exist. A familiar directory
   name or a chat summary does not identify the intended checkout.

# Reviewing changes

Review the delivered candidate, not the author's confidence or task status.
Support findings with the user's contract, the actual diff and observable
behavior. A review is useful only to the extent its inspected scope is clear.

## Establish the review inputs

1. Read the user outcome, acceptance commands, preserved behavior and scoped
   file ownership. Confirm the assigned checkout and applicable instructions.
2. Identify base and candidate revision, plus uncommitted and untracked inputs.
   Inspect the diff and affected artifacts directly. Verify referenced paths.
3. Read existing check output, command, exit status and input identity. Treat
   author and worker reports as leads; do not turn a result label into evidence.

# Using Done is a claim

Turn the user's outcome into a bounded change and a report supported by current
observations. Scale the process to the task. This entry skill works on its own;
the optional routes below add depth when those skills are actually available.

## Establish the task

1. Identify the requested outcome, exact repository or worktree, existing
   authorization and owned files. Read applicable project instructions.
2. Confirm supplied inputs exist. For a requested new file, confirm its parent
   and intended role. Inspect the current revision and uncommitted changes.
3. Before editing, name the acceptance command and observable result, plus
   relevant broader checks. A prose change may need a structure check and

# Whose red is it

A red says the suite failed, not who failed it. The branch's log alone may not
separate "the change is wrong" from "main was already broken". Use a matched
control where possible, investigate differences, and report uncertainty before
you retry, revert or block on the red.

## Procedure

1. **Read the error text first.** These errors can point to setup or command
   problems, but can also result from the change:
   - `command not found`, exit 127, a missing interpreter or tool;
   - `file or directory not found` for the test path itself (exit 4 in pytest);
   - `no tests ran` / nothing collected (exit 5 in pytest);