Implement
Implement the accepted outcome. Repair ordinary known defects directly. Use the existing
intent; no Plan, Recall or Learn worksheet is owed for a clear edit. Implement
owns source changes and factual checks; the runtime derives identity and receipts.
Rules that decide the result
- Fix the cause, not the oracle. Never loosen an assertion, tolerance,
golden, fixture or suppression, or substitute a mock or placeholder, to turn
a check green. A check that fails against accepted behavior points at a
product defect; changing what the check accepts is an acceptance change and
needs caller authority.
- Find live consumers before editing. Search the callers, readers, scripts,
docs and tests of every edited function, type, path, format or message. For
each one, state whether the change affects it and which check covers it. When
retiring or renaming, consumers include installations, lookups and old-name
invocations; preserve historical provenance. If the replaced interface never
merged or shipped and every consumer update fits the scope, update them and
delete the old version in the same change, with no alias or shim; otherwise
keep the old version working or report it.
- Name discriminating checks. A behavioral change preserves RED
for the expected missing behavior: name the check that fails before the edit
and passes after, plus the check for each affected consumer.
- Report only what ran. Give exact commands and results. List every check
you did not or could not run as not run. Never call unrun work verified,
fixed or green. Output can show as soon as a command runs, so keep secrets
out when you build it: credentials stay in the environment, output that may
carry tokens goes to a file, and only redacted excerpts are shown.
When changing a public failure path, preserve its native failure signal and
check that its recovery advice matches any work already performed. For uncertain
write outcomes or unattended callers, use only the relevant checks in
Test's error recovery method.
For an accepted bounded shortcut, review feedback or a defect your change
introduced, an authorized commit, history rewrite or merge conflict, dependency
upgrade, removal, blocked operation, a decision read from another tool's state
or your own uncertain write, use only the matching change safety method.
These methods preserve existing authority; they grant no new operation.
For authorized service operations, load only the relevant procedure from
operations methods (reliability, delivery, incident
recovery, resilience, toil); ordinary edits owe no operations phase.
Workflow
- Read intent, acceptance, scope and repository boundaries before the first
write; reuse loaded contracts. RPI boundaries
apply when that workflow is explicitly selected. Caller-selected episode
tracking follows the session association reference;
keep unknowns explicit and invent no parentage or second tracker. Note the
revision and files already modified, staged or untracked; report only your
own as changed, and ask the caller before editing one holding others' edits.
- Carry the accepted behavior examples forward unchanged. Use repository
domain names in symbols and tests; check observable outcomes through the
relevant interface. Run the smallest applicable check before and after
editing. Pure refactors, relocations or docs may have an honest green
baseline. Prefer existing tests or small discriminating probes.
- Make the smallest in-scope change. When repairing discovery or checks,
preserve the consumer's existing input selection; fixing an error path does
not authorize a wider scan. Use a negative control when exclusion matters.
Check a representative change against existing constraints before bulk
propagation, and the authored source set before broad regeneration. A
scripted edit across files first confirms that each anchor matches exactly
once; on zero or several matches, write nothing and re-derive it. Repair
known failures directly and verify the exact result with a check; a repair
does not start another review. A disproved assumption may change the
approach within scope; use Plan only for consequential uncertainty.
- Read the repository's actual check recipe, including instrumentation and
environment, rather than reconstructing it from memory. Run targeted tests
and lint/static checks before broad integration, and required full checks at
integration. Reuse exact-input receipts only while source, tool and relevant
environment match. Neither bypass required hooks nor replay a check just to
rename its receipt. A required CI job's known failure is actionable before
the run ends: repair it within scope, keep the failed subject's evidence and
rerun affected checks. Pending jobs do not imply success. A new check, hook
or lint rule counts once the aggregate command or CI runs it (a Git hook needs
an install path;
.git/hooks is not cloned) and it fails on a deliberate
violation; else list it under gaps as not wired. Use a local server already
on a port only if it provably serves this checkout; stop only processes you started.
- Refactor while acceptance remains green. Inspect changed tests, fixtures,
goldens, tolerances, suppressions and specification text against original
intent before handoff. Reread that intent at its source, not a compacted
summary, and check the whole delta against it, untracked files included.
Remove leftovers of abandoned approaches, temporary probes (one shared
marker lets a single search prove none remain) and files your checks made;
list any path you cannot explain under
gaps as a scope amendment.
- Have the runtime derive actual changed paths and content identity. A delegated
increment awaiting integration returns an exact commit or runtime-derived
content digests, author context ID and check facts in the existing handoff.
The integrating caller derives
subject-manifest.v1 (AgentOps schema
schemas/subject-manifest.v1.schema.json) over the complete final subject
before judgment; an independently judged increment needs its own manifest.
Do not generate both merely because work was delegated.
- At that boundary, when the repository records AgentOps evidence bindings
and changed paths affect bound acceptance evidence, run
ao provenance evidence-orphans --root <repo-root> with one --changed <path> per derived path, retain its actual output and refresh affected
bindings after repairs. Without ao, list the orphan scan under not run.
Never invent or suppress the orphan list.
- Return the handoff below, then stop.
Handoff
Keep full logs at their source; do not duplicate inventories or status documents.
changed: <runtime-derived paths>; identity: <commit or content digests>
checks: <exact command> -> <result>, one per line; before and after for a behavioral change
not run: <check> -> <reason>; "none" only when every relevant check ran
consumers: <file:line> -> <covering check, or "uncovered">
gaps: <missing or truncated evidence, known failures, scope amendments needed>
cause: <defect repairs only: trigger -> mechanism -> symptom at file:line; sites left as follow-up>
Report an uncovered live consumer for a caller scope amendment and continue
independent authorized work. Disclose a reversible implementation choice only
when its alternative has a material consequence the caller may want to change;
name the choice, alternative and reason in the handoff, without a fixed worksheet.
Generated companions already included as scope require no new approval; a change
to accepted direction, behavior or acceptance always needs caller authority.
Diagnosis, scaffolding and delegated work
For an unexplained failure, first match the reported symptom and reduce the
reproduction. Confirm the failing run executes the code you think: revision and
local edits, a fresh build rather than a stale artifact or installed binary,
the resolved runtime and dependency versions, and required environment values.
Ground the leading cause in an observation, not in how the code reads, and name
its strongest rival. State one causal prediction, test it with a check the two
causes predict differently, and repair the cause supported by the result.
Change one thing per probe; when a prediction fails, revert that change, name
what ruled the cause out and form a different cause, not a variant of it.
Rerun the original scenario. Do not keep collecting hypotheses after the cause
is understood. For intermittent verdicts, leaked test state, suspected races, a
hung/crashed process, a regression from a known-good state, a failure crossing
components or repeated disproved causes, use only the matching experiment in
difficult failures. This compact diagnosis
path is informed by Matt Pocock's engineering skills.
When scaffolding is the requested change, start from the repository's existing
layout and a working vertical slice. See scaffold references
only for the relevant tool shape, and generic scaffold examples
when the repository has no suitable pattern. Avoid placeholder success paths and
a new framework for a one-off operation.
Prefer current-session execution. If delegation is authorized and useful,
partition independent writes in isolated workspaces; shared generators and
integration serialize. Supply each lane its intent, acceptance, scope and review
owner, then integrate its exact content and check facts. A selected wave ends with the
caller-requested wave result; do not invent another wave. One fresh review of
the integrated candidate can cover unjudged increments; when the integrator
owns that review, workers return their handoff without commissioning another.
Preserve any separately required lane judgments; a successful process exit is
not semantic PASS.
Agent Native supplies optional dispatch mechanics.
An explicitly requested one-shot adapter dispatches each supplied operation
once, reports its output or error, and stops. Show dispatch count and failure
reporting with a dry-run or fixture. It does not silently acquire a scheduler,
retry controller or store. Factories require the caller's selection.
Finish
Specialists advise only. Known defects stay implementation work; a genuine
causal stall permits at most one bounded fresh helper within caller authority.
Respect remaining caller/native bounds and reserve finishing capacity; retries reset neither.
Return facts, not semantic PASS. An implement-only handoff does not authorize
Git, tracker or delivery transitions; existing caller authority remains usable.
A full outcome request finishes on its checks and CI. It continues to one fresh
independent judgment only when the caller asks, a mistake cannot be cheaply
undone after it lands, or no deterministic check covers the changed behavior.
RPI is optional and explicitly selected. Success is working behavior with usable
evidence, not volume of logs or process artifacts.