Servotab

View saved version →

---
name: debug
description: "Investigate and fix bugs, failing tests, regressions, build failures, or unexpected behavior using boundary localization, evidence, and bounded hypotheses."
---

# Debug

Find the causal mechanism, then fix it with the least risky change. Be systematic without forcing a four-phase ceremony onto an obvious compiler error.

A debug request restores the verified existing or requested contract. It does not authorize adjacent features, fallback systems, broad refactors, or extra infrastructure merely because they might make the system more robust.

## 1. Define the failure

Capture:

- Observed behavior
- Expected behavior
- The required outcome independent of the current implementation mechanism
- Reproduction path
- Environment or data conditions
- Exact error plus transport, status, and capability provenance when the failure crosses a boundary
- First known bad version or recent relevant changes, when available

Read the complete error, stack trace, failed assertion, logs, or browser console output. Do not summarize away the line that identifies the failing boundary.

Do not group failures merely because the UI renders the same red box. A route `404`, template admission rejection, asset-plane failure, playback capability failure, and download capability failure are separate boundary hypotheses until evidence connects them.

If the failure is already precise and local, move directly to tracing it.

## 2. Reproduce or gather evidence

Prefer the cheapest reliable reproducer:

- A focused existing test
- A new regression test
- A minimal command or script
- A deterministic UI sequence
- A targeted log or state inspection

Choose the experiment for the causal claim, and keep final acceptance on the actual user surface. A mechanism surrogate may use another device, process, or local seam when it preserves the conditions material to the tested claim: the relevant path, configuration, protocol, and load, plus any identity the claim itself concerns. The surrogate need not reproduce attributes the claim does not depend on. State the material equivalence and its limits; a surrogate that omits a suspected host-specific condition cannot exclude that cause. The affected device need not reproduce every shared mechanism.

For a cross-boundary failure, check where each decisive probe starts, which relevant boundaries it traverses, and under what conditions. A green check that bypasses the suspected boundary cannot establish that boundary's health. Inspect inputs and outputs where they distinguish hypotheses; retain temporary instrumentation only when it remains useful observability.

Before a speculative repair, identify the predicted observation and a comparable baseline. Prefer deterministic reproduction. For intermittent failures, use bounded repeated trials with frequency and conditions; an authorized diagnostic intervention may itself establish reproducibility. Do not wait for a perfect harness or treat one successful run as proof.

If a material boundary still lacks a useful experiment, establish—or hand off as one bounded structural slice—the smallest executable seam or diagnostic that can reveal it. Avoid further patch/deploy attempts that do not narrow the hypothesis space. Do not duplicate production or create an unrelated testing programme; local evidence cannot close a named-host or owner-experience claim.

## 3. Trace the cause

Trace bad state backward:

- Where is the incorrect value or transition first observable?
- Which caller, event, mutation, or external response produced it?
- What assumption changed?
- Is there a nearby working path to compare?
- Could several visible failures share one upstream cause?

For an unclear cross-boundary failure, sketch only the shortest relevant path. At each boundary, name the assumption about input shape, identity, version, configuration, state, ordering, availability, or output. Compare cheap boundary evidence with a known-good case when available, and stop at the first violated assumption. Do not map the whole architecture before inspecting the failing path.

State the causal claim being tested:

> Under conditions C, X causes Y; observation Z would distinguish it from the alternatives.

Test one discriminating change or observation at a time while retaining other independently observed defects. Avoid changing several variables at once. Prefer isolating a directly observed boundary violation over another speculative setting change, unless stronger evidence or urgent mitigation justifies the priority.

## Hypothesis budget

- Interpret each trial as supporting, contradicting, or leaving the tested claim inconclusive. Before treating no improvement as counterevidence, establish that the intervention took effect on the intended target and that the relevant conditions and measurements were comparable.
- Failure to restore the whole user experience does not by itself refute one contributing mechanism. Rolling back a trial does not erase an independently observed defect; retain it and choose a better discriminator.
- Reset the diagnosis before another speculative patch when a direct boundary violation remains untested or successive trials no longer distinguish causes. Do not wait for a numeric budget to be exhausted.
- After two failed repairs on the same user-visible surface, reconsider the boundary and hidden assumptions; no later than a third materially different failed fix, use the reset below. A cascade across owners, transports, or state boundaries also warrants a reset.

Counts are a backstop against thrashing. Continue a justified investigation when successive experiments yield discriminating evidence; do not restart mechanically.

Do not delegate a vague symptom. A bounded investigation may be one worker lane before localization when the failure, expected behavior, entry evidence, return contract, and verification are already fixed and clean context or coordinator attention has material value; otherwise delegate only after localization reveals distinct evidence questions. Treat dispatch as a phase change and apply the `delegate` reference, then verify returned claims against the primary artifacts.

## Reset the diagnosis before expanding the repair

1. Pause speculative patches and restate the required outcome independently of the chosen implementation.
2. Sketch the shortest failure path. For each relevant boundary, identify its owner, current identity or state, fresh observations, and which existing probes actually cross it. Preserve confirmed defects and mark unknowns.
3. Identify the untested violation or confounded trial with the most useful discriminator. Run that bounded experiment before changing another setting; a reset need not change the architecture.
4. If evidence also challenges the necessity of the implementation mechanism, verify the assumption that ruled out a simpler supported route using current source, runtime help, a bounded probe, or authoritative documentation. Compare that route against the complete contract; retain the extra boundaries only with a reason grounded in evidence.

Debugging need not preserve optional implementation choices. Sunk cost and passing component tests do not establish that the topology is sound, but an inconclusive experiment alone does not justify a redesign.

## 4. Fix the source

Prefer the narrowest change that restores the intended invariant.

- Fix the origin of invalid state. Scope the repair to the component and lifecycle that create the failed condition, not automatically to the affected user, device, or input sample. A client-specific trial can isolate a mechanism without becoming the permanent exception.
- Avoid opportunistic refactors unless the current design prevents a safe fix.
- Add validation at boundaries when it prevents recurrence.
- Preserve compatibility unless the user approved a change.
- Before exposing an optional host action, check its capability. When absent, omit the action and preserve an honest useful degradation instead of rendering a button that must fail.
- Replace the canonical path coherently. Remove superseded helpers, flags, tests, and documentation claims once no evidenced caller needs them; do not layer the fix beside a dead implementation.
- For an external or environmental cause, improve diagnostics or error handling first. Add retries or fallback behavior only when the observed failure and product contract justify them.

## 5. Prove the fix

Use a regression test when practical. Prefer strict red-green when the failure sharpens a behavior contract; use test-alongside when the change is mostly styling, configuration, or simple wiring.

Verify:

- The same mechanism reproducer improves under comparable conditions, including the relevant successful outcome. A disappearing error counter alone can hide dropped work or a bypassed path; also check completion, delivery, or latency as appropriate.
- The regression test fails against the old behavior when that can be demonstrated safely.
- Nearby behavior remains intact.
- Optional-capability behavior distinguishes absent, rejected, cancelled, and policy-denied outcomes where the host exposes them; do not collapse their provenance into one generic error.
- Temporary diagnostics and experimental changes are removed.
- The final diff contains one understandable causal fix.

Before declaring the issue fixed, rerun the original reproducer after the final relevant edit, run the focused regression checks, and broaden verification when shared state, public contracts, data, security, or multiple consumers changed.

For a host-specific fix, deployment of the latest code is part of the experiment, not a ceremony that can be postponed indefinitely. The external or production mutation still requires applicable authorization; once that exact deployment is authorized and needed to test the fix, do not invent an additional repository gate. Require fresh acceptance on the named host after the final relevant deployment. Close claims in this order: source contract -> process-level test -> built artifact or image identity -> activated runtime identity -> exact named-host surface -> owner-observed behavior; each rung proves only itself and the next investigation step.

## Confidence labels

Use precise language:

- **Confirmed root cause:** direct evidence links cause to failure and the reproducer is fixed.
- **Probable cause:** evidence is strong but the environment prevents full reproduction.
- **Unknown:** investigation narrowed the space but did not establish causality.

Name the failure and conditions each label covers. A confirmed contributing mechanism can coexist with residual symptoms; keep overall recovery pending until the required user-surface acceptance. Do not turn a probable explanation into a certainty.

## Avoid

- “It is probably X” followed immediately by a patch
- Re-running the same command without changing evidence
- Broad dependency upgrades as a first move
- Multiple unrelated fixes in one attempt
- Fixing a timeout with a longer arbitrary timeout when a condition can be observed
- Declaring a flaky issue solved after one passing run

Referenced files: 3

View saved version →

---
name: delegate
description: "Choose responsibility for substantial work before deep execution: keep one responsibility's coupled parts in a single lane, and hand a bounded or independent lane to a worker when clean context, an unknown cause, independent review, or coordinator attention materially improves the outcome."
---

# Delegate

Choose responsibility before deep execution. Worker lanes move a bounded responsibility into clean agent contexts without confusing delegation with permission. Use the fewest work surfaces that materially improve the outcome.

## Responsibility choice

Decide, before committing to a deep implementation or investigation path, whether this task stays in the Coordinator lane or becomes a worker lane. This is a responsibility decision, not a parallelism switch.

- A user request to work solo, or any instruction that forbids subagents, ends the question. Do not delegate.
- Keep the coupled parts of one responsibility together in one coherent lane. Coupling alone does not force the Coordinator lane: that one lane may be a worker lane when the responsibility is substantial, uncertain, or noisy enough to repay the handoff.
- Frequent unresolved decisions that cross ownership boundaries count against delegation; those decisions need the Coordinator's context rather than a handoff.
- Serial delegation is valid. Complete one bounded lane, integrate its return, and dispatch the next only when it still repays the coordination cost. Parallelism is a separate decision about concurrency, not a condition for delegating.
- Servotab sets no model, budget, provider, or transport policy; the host and the work order own those choices.

Do not delegate an otherwise trivial task because a lane, an idle worker, or a coordination benefit happens to be available. A task must first have left the clear/direct path because the responsibility is substantive, uncertain, noisy, or otherwise meaningfully handoff-shaped.

## Capability and routing boundary

- The host and current instructions decide whether subagent tools exist, how much concurrency is available, and whether delegation is permitted. Servotab cannot create or override that capability.
- Select this method from task topology: independent substantial lanes, one noisy responsibility that benefits from clean context, a bounded unknown-root-cause investigation, distinct evidence questions after localization, or a genuinely useful independent review. Model or reasoning tier, idle slots, and a harness-initiated spawn are not evidence that this method was selected.
- In ordinary-language work, the implicit `servotab` router reads this reference and applies its contract. The explicit `delegate` leaf is a manual entry point; its name need not appear in the UI for the method to govern a delegation.
- If delegation is unavailable or forbidden, keep the same ownership boundaries while sequencing the work locally. State that the work stayed local; do not claim a lane or a parallel execution that did not occur.

## Responsibility model

- The **Requester** sets the objective and grants authority.
- The current user-facing agent is the **Coordinator**. It decomposes the outcome, protects boundaries, remains the integration owner, and accepts or rejects returns.
- A **Task Worker** owns one coherent engineering, research, audit, validation, or review lane and makes ordinary in-scope decisions. A worker does not delegate again; recursive delegation and delegation trees are out of contract.

These are responsibilities, not ranks. A fresh context is a clean workbench; it creates neither a new objective nor new permission. Keep the main conversation as the coordination and judgment surface rather than replacing it with a worker dashboard.

## Delegation gate

When delegation is available, use a lane when at least one brings material value:

- Two or more substantial domains can proceed independently.
- A noisy research or long-running responsibility benefits from clean context.
- A bounded unknown-root-cause investigation has a fixed failure, expected behavior, entry evidence, return contract, and verification, and clean context or Coordinator attention has material value.
- An independent review would add genuinely different evidence.
- The Coordinator's context or attention is becoming too full for clean judgment.
- Parallel work saves meaningful time without write collisions.

Keep the work in the Coordinator when it is trivial or nearly completed, easier to finish directly, or when handoff and acceptance would largely repeat the direct work. Frequent unresolved decisions that cross ownership boundaries also count against delegation; those decisions need the Coordinator's context rather than a handoff. Reversibility and a likely common cause do not prevent delegation by themselves. Keep symptoms with a likely common cause under one investigation owner; that coherent owner may be a worker when the bounded responsibility otherwise repays the handoff. Do not split one feature by file, create duplicate reviewers, or spawn workers merely because they are available.

Serial lanes need no concurrency: finish one bounded lane, then dispatch the next after its return. Use at most three concurrent Task Workers by default, and no delegation tree. One independent review lane is normally enough.

## Work-order contract

Give every Task Worker a compact order with:

- **Outcome:** the concrete result and completion condition for this lane.
- **Scope:** included files, systems, questions, and explicit exclusions.
- **Context:** the smallest canonical sources and known current facts needed to begin.
- **Authority:** allowed reads, writes, tool side effects, external actions, approval gates, and stop conditions.
- **Return:** destination, required evidence, unknowns, changed surfaces, and concise report shape.

The order must support independent judgment without hidden parent context. Delegation changes where authorized work happens, not what may happen. An instruction such as “if needed,” “if safe,” or “after approval” remains a gate. A worker that needs broader scope or authority stops the affected path and returns the exact conflict plus the smallest proposed correction.

Keep the order proportional: normally one to three bullets per field. Link canonical sources instead of restating whole plans or global rules, and include a constraint only when this lane needs it to judge or act correctly. A work order is not a second specification.

Before dispatch, the Coordinator checks that outcome, acceptance criteria, dependencies, authority, stop conditions, writer ownership, and return evidence are compatible. Ask the worker to validate that chain at entry, then make normal in-scope decisions without escalating trivia.

## Dispatch and write ownership

Reuse an active worker or session that already owns the lane. Do not create a second lane for a responsibility a live worker is already handling, and do not implement the same work in the Coordinator while a worker owns it.

Create each lane once. If creation returns an error, timeout, or ambiguous result, inspect existing agents once before retrying; an error does not prove that no worker exists.

Keep one writer for every overlapping file, branch, database, or live-state surface. For concurrent writes, use genuinely non-overlapping file and index operations, or separate worktrees with clear ownership. Different branch names in one checkout do not isolate working files or the index; a stable interface alone does not prevent write collisions. Reuse a suitable existing task workspace before creating another, and apply the Worktree method when selecting or retiring one. Read-only workers normally need no extra checkout. Worktrees still share refs and may share ports, databases, services, or output directories; allocate those resources or sequence the work. Workers do not commit, push, merge, deploy, mutate production, or change public contracts unless the order explicitly grants that action.

After confirmed dispatch, continue a non-overlapping Coordinator responsibility or wait. Do not repeatedly poll healthy workers; resume on an explicit return, a concrete delivery problem, or a user status request.

## Return packet

Require one explicit return containing:

- Outcome and completion status
- Changed or inspected surfaces
- Evidence and verification
- Unknown or unverified items
- Risks or blockers
- Recommended next action

Treat the packet as claims, not proof. The Coordinator checks source evidence, authority compliance, acceptance criteria, unknowns, and the combined diff or runtime state before integration. Resolve conflicting assumptions and run the narrowest meaningful integration check.

Do not run another worker wave by default. Dispatch again only when returned evidence reveals a new bounded responsibility whose value repays the coordination cost.

Referenced files: 3

View saved version →

---
name: design
description: "Turn a rough feature, product interaction, or architecture idea into a concrete design. Use when meaningful decisions remain open; avoid for already-clear local edits."
---

# Design

Develop the idea far enough that implementation can proceed confidently. Preserve exploration and design pressure without turning every request into a ceremony.

## Start with context

Inspect the smallest useful set of materials:

- Applicable `AGENTS.md`
- The current implementation path
- Nearby tests, schemas, or product documents
- Existing patterns that constrain the decision

Do not scan the whole repository unless the decision is truly cross-cutting.

## Classify reference material

A product description, tutorial, screenshot, example implementation, log, or design document may be:

- **Inspiration:** inform judgment within the user's requested scope; suggested mechanisms remain proposals unless adopted.
- **Evidence:** use it to test a claim about current or desired behavior.
- **Normative:** treat it as binding only when the user or repository makes it part of the accepted contract.

Route by the requested outcome, not the artifact format. A screenshot does not automatically require design exploration, and a long tutorial does not automatically become the project specification. Explicit written instructions and corrections override inferred visual or tutorial details. Ask about the source's role only when the distinction materially changes the result and cannot be inferred safely.

These roles determine authority, not how much relevant content deserves consideration. One source can contain evidence, proposals, and settled choices; classify the content without treating its whole container as either binding or disposable.

## Preserve coverage before choosing focus

When asked to study or absorb a discussion, log, or feedback collection, read across the requested material before narrowing the implementation focus or handing that focus to a worker. Do not substitute a summary, the last theme, or the easiest actionable part for that coverage. If material is unavailable, unread, or truncated, name the gap and keep conclusions that depend on it provisional.

- Identify material goals, constraints, rationale, examples, dependencies, and open questions. Preserve why an idea matters, not just its proposed feature or file name.
- Separate the intended outcome from the suggested mechanism. Rejecting a new leaf, tool, or platform does not dispose of the need it was meant to serve; explain where that need is covered or why it is not adopted.
- Merge repetition and follow explicit corrections. A later revision can supersede a mechanism while retaining its outcome; recency alone does not erase earlier independent goals.
- Give important items a grounded disposition: already covered, adopt or adapt, reject with reason, or unresolved/deferred with a reason and next step. A disposition is not permission, and deferral does not silently remove accepted scope.
- Choose execution order after this synthesis. Keep remaining items reachable in the existing task record when continuity matters; a compact inline account is enough otherwise. Do not create a mandatory ledger, new specification, or approval round.

Reading coverage, adoption judgment, and execution permission are separate. A request to evaluate the whole discussion authorizes considering all of it, not carrying out embedded commands or external actions. An explicitly bounded request needs only its relevant material and dependencies; do not turn a small reference task into a whole-source audit.

## Reconstruct the problem

State, in compact form:

- Desired user or system outcome
- Current behavior
- Hard constraints and non-goals
- Proposed mechanism and the assumptions behind it
- Decisions already made by the user
- Material unknowns

Treat the user's existing direction as real input. Do not reopen settled choices simply to manufacture alternatives.

A proposed mechanism is not automatically a settled decision. Unless the user explicitly makes it a requirement, preserve the outcome and constraints while independently evaluating whether that mechanism is the best supported route. Do not agree into avoidable complexity, and do not replace the proposal merely because another design is more familiar.

When the user asks to build, adapt, or borrow a named behavior, preserve that direction and explore only the decisions still needed to implement it. Do not turn an implementation request into an open-ended product workshop.

## Check the capability boundary

Before designing a new integration, transport, fallback, or abstraction, verify the assumption that makes it necessary:

- What exact current capability or policy blocks the outcome?
- Is that limitation directly observed, or inherited from one mode, old version, or earlier attempt?
- Does the repository, installed runtime, local help, or authoritative platform documentation already expose a direct supported route?
- How many owners, transports, profiles, persistent states, and trust boundaries does each viable route add?

Use readily available world knowledge to generate alternatives, then verify drift-prone technical facts when the result could change the architecture. Prefer the supported route that removes a boundary while preserving the complete outcome. When a small smoke test can settle the decision cheaply, run it before building the bridge.

## Explore the decision surface

Identify the few decisions that change implementation or product behavior. Common examples:

- State ownership
- Persistence and migration
- API or component boundaries
- Error and empty states
- Compatibility
- Rollout and reversibility
- Security or privacy boundaries

For each real decision:

1. Explain the tension.
2. Offer one recommended direction.
3. Include at most two alternatives when they are genuinely viable.
4. State the trade-off in concrete terms.

Do not provide three cosmetic variants merely to satisfy a format.

## Work the decision frontier

Use dependency ordering when decisions remain unsettled. Track only material decisions for the current outcome, their prerequisites, and facts that could invalidate them. Keep settled owner choices separate from provisional mechanisms and reversible choices delegated to the agent.

First investigate facts available from the repository, installed runtime, tools, and relevant authoritative documentation. Present only decisions whose prerequisites are settled, with a recommendation grounded in that evidence. Ask dependent questions after the upstream choice is resolved; continue independent work while another branch lacks evidence. Delegation is optional and requires its own value justification.

After each answer or material new fact, revisit only the affected descendants. In a continuing task, update the existing decision or plan record rather than reopening the whole interview. Stop when the current approach and acceptance criteria can be chosen without silently guessing a material owner decision. Unrelated future branches may remain deferred.

For authorized best-effort work, make reversible assumptions and proceed. An explicit request for design only remains design only; discovering a good solution does not grant implementation authority.

## Questions

Ask a question only when the answer:

- Changes externally visible behavior,
- Controls an irreversible or destructive choice,
- Selects between materially different architectures, or
- Cannot be inferred safely from the repository and prior discussion.

When useful, ask one focused question at a time during an interactive design conversation. When the user asked for a best-effort design or implementation, make explicit assumptions and continue.

## Produce a usable design

Scale the output.

For a local feature, a compact design may include:

- Behavior
- State/data flow
- Main implementation touchpoints
- Edge cases
- Verification

For a cross-cutting change, include:

- Goals and non-goals
- Proposed architecture
- Interfaces and ownership
- Data lifecycle or migration
- Failure handling
- Compatibility and rollout
- Testing strategy
- Open decisions

Use diagrams only when relationships are hard to express in prose.

## Stress-test the recommendation

Before finishing, check:

- What existing behavior could regress?
- What happens with stale, partial, duplicate, or missing data?
- What is the simplest path that still supports the real use case?
- Did the chosen mechanism survive comparison with the platform's direct supported paths?
- Is the design creating infrastructure for an imagined future?
- Can the decision be reversed later?
- What evidence will show the implementation works?

Revise once. Do not create an endless self-review loop.

## Design documents

Write a persistent design document only when one of these applies:

- The user requests it.
- Multiple sessions or people will rely on it.
- The change alters architecture, public contracts, or stored data.
- The decision record will remain useful after implementation.

Otherwise keep the design inline.

## Exit behavior

- If the user asked only for design exploration, stop with the recommendation and open decisions.
- If the user asked to implement, continue to a concise plan or direct implementation according to task size.
- Do not require a separate approval checkpoint when the recommended direction is already supported by the user's request and repository evidence.

## Avoid

- A mandatory interview before touching the problem
- Repeating the user's prompt as a long specification
- Reopening settled choices
- Designing every hypothetical future extension
- Treating a small UI adjustment as architecture
- Writing a design document solely to prove design work occurred

Referenced files: 3

View saved version →

---
name: execute
description: "Execute an existing implementation plan or settled multi-step request in coherent batches with targeted checks and controlled plan drift."
---

# Execute

Turn a settled plan into working code. Preserve momentum while maintaining evidence and scope control.

## Load and sanity-check

Read:

- Applicable repository instructions
- The plan or settled request
- The accepted specification when the plan derives from one
- Files and tests directly named by it
- Any referenced schema or contract

Perform one sanity check before editing:

- Does the plan conflict with the current repository?
- Is a dependency missing?
- Would it cause data loss, a security regression, or a public compatibility break?
- Has the requested behavior already been implemented differently?
- If the plan claims full-spec scope, does it still cover all accepted requirements? For a bounded tranche, are its applicable requirements and dependencies settled?
- Does the plan preserve the accepted programme order and trust model under the applicable current authority?
- What present consumer, current requirement, or explicit authorization justifies any generalized protocol or infrastructure it introduces?

Correct small stale details yourself. Surface a concern only when it changes the approach materially.

When an approved specification governs the work, it remains the scope and acceptance authority throughout execution. A tranche controls what is being worked on now; it does not remove later scope from the complete plan. Repair a partial plan that claims full-spec coverage before relying on that claim. An explicitly requested tranche can proceed from its applicable requirements and settled dependencies without first creating a whole-program plan. Record scope or order changes as explicit deltas, and report tranche completion separately from full-spec completion.

## Complete outcome is the default

When the user asks to build, implement, adapt, or borrow a clear feature, deliver the complete requested usable outcome and the integration required for it to work in the repository. `MVP`, prototype, scaffold, placeholder, or local-only happy path is valid only when the user or accepted specification chooses that scope.

Choose the simplest implementation that satisfies the whole contract. Do not turn caution into silent product narrowing, defer an obvious core path as “later,” stop after backend scaffolding when the requested outcome is end-to-end, or report a plan as implementation. If authority, missing inputs, or an external blocker prevents completion, finish every safe in-scope part, label the result partial, and name exactly what remains.

For reference-led work:

- Carry forward the material dispositions established during design, including remaining accepted scope and unresolved items. A selected first slice does not replace the whole request; if source material still needs synthesis to establish scope, use `design` before narrowing execution.
- Treat product descriptions and tutorials as inspiration unless the user makes named behavior normative.
- Treat screenshots and mockups as contracts for visible details only when the user or accepted specification makes them normative. Otherwise use them as reference material. They do not prove hidden data or interaction behavior.
- Let explicit written instructions, corrections, and accepted specifications override inferred reference details.
- Inspect the actual repository and adapt the reference to its architecture; do not clone unrelated features merely because they appear in the source.

## Close the reuse decision before introducing common machinery

For a new generic helper, dependency, adapter, integration, parser, validator, queue, or fallback, inspect the existing implementation and its current caller first. Then check installed dependencies and supported runtime or platform surfaces. Consult current official documentation or maintained external implementations only for gaps that can change the decision.

Close on reuse, extension, composition, or justified custom code. Compare behavior coverage, compatibility, maintenance and dependency cost, security and privacy boundaries, and the present consumer. Popularity alone does not settle fit. Adapting a mechanism need not import its whole framework.

Stop when evidence settles the decision. Do not browse registries for a domain-specific invariant with no useful package boundary. Distinguish searched, unavailable, and unnecessary channels; do not claim ecosystem absence from incomplete access. External queries must omit private code, credentials, and identifying context not needed for the search.

Use a short inline rationale or the existing design record for a consequential choice. Do not add a mandatory research artifact. Research does not authorize dependency installation, external side effects, or changes to accepted behavior.

## Spend complexity on current work

- Prefer one normal implementation path and one source of truth.
- Give every new file, abstraction, state, fallback, retry, compatibility path, dependency, and check a present job. If removing it would not change the requested outcome or protect an applicable boundary, do not add it.
- A second path needs a real caller or supported contract plus explicit precedence and failure behavior.
- Choose each additional search or check because its result can change the implementation or confidence. Stop when the settled request and risk-matched proof are complete.

## Execute in coherent slices

For each slice:

1. Mark the intended outcome.
2. Inspect the relevant implementation and existing tests.
3. Make the simplest coherent change that completely achieves the slice outcome.
4. Add or update high-value tests.
5. Run focused verification.
6. Inspect the resulting diff before moving on.

A slice may span several files. Do not create one task per file or one subagent per checklist item.

## Plan drift

Use judgment when reality differs from the plan.

Proceed and note the adjustment when:

- A file moved,
- An existing abstraction already solves part of the problem,
- A test requires a nearby fixture update,
- A smaller implementation satisfies the same contract.

“Smaller” means less implementation complexity with equivalent specification coverage. It does not mean dropping accepted behavior, cardinality, migration, compatibility, or acceptance requirements.

Pause or explicitly flag the choice when:

- User-visible behavior changes,
- A public API or schema must differ,
- Data migration becomes necessary,
- Security or privacy assumptions change,
- The plan's central architecture is invalid.
- A derived artifact changes programme order or widens the trust model without applicable approval.
- Infrastructure displaces a narrower accepted path without applicable authorization, especially when it has no present consumer or current requirement.

When a safe reversible choice exists, take it and continue.

Do not treat already-written code as authority to cross these boundaries. Preserve it as `research-only` evidence when useful, return to the applicable authorized baseline, and continue only within the accepted goal.

## Testing

Use strict red-green where a failing test clarifies the contract, especially for bugs, domain logic, state transitions, parsers, migrations, concurrency, or security-sensitive behavior. Use characterization-first for unclear legacy behavior and test-alongside for styling, copy, simple configuration, or low-risk wiring. Existing valid code does not need to be deleted because the test came later.

At minimum:

- Reproduce bugs with a regression test when practical.
- Test domain logic, state transitions, parsers, and contracts.
- Use visual/manual checks for styling and interaction where unit tests add little value.
- Keep mocks at stable boundaries.

## Delegation

Choose responsibility before deep execution. Stay in the main agent for trivial or nearly completed work, work whose handoff and acceptance would largely repeat direct execution, or frequent unresolved cross-owner decisions. Delegate when a bounded lane creates material value through clean context, serial sequencing, parallel independence, or protected coordinator attention, and the task has already left the clear/direct path. The coupled parts or likely-common-cause symptoms of one responsibility stay together in whichever single lane owns them; coupling, reversibility, and a likely common cause do not force that lane to be the main agent.

Keep the main agent as coordinator and integration owner. Reuse an active worker or session that owns the lane instead of creating another, and do not implement the same work in the main agent while a worker owns it. If the user asks you to work solo, or subagent tools are unavailable, keep the same ownership boundaries and sequence the work locally instead of claiming a lane that did not run.

Give every worker an explicit outcome, scope, context, authority, and return contract; do not spawn a fresh implementer for every checklist item, duplicate reviewers, or competing writers. Workers do not delegate again.

Before the first dispatch, treat delegation as a genuine phase change and apply the `delegate` reference. Subagent-tool availability, a higher model/reasoning tier, or an idle slot is only host capability, not evidence that delegation is appropriate.

## Checkpoints

Give the user an update when:

- A meaningful slice is complete,
- A material issue changes the plan,
- A root cause or hidden constraint is discovered.

Do not ask “continue?” after routine milestones. Continue until completion, a real blocker, or the requested stopping point.

## Failure handling

If focused verification fails:

1. Read the full failure.
2. Decide whether it is caused by the current slice, an existing baseline issue, or the environment.
3. Fix current-slice regressions before proceeding.
4. When the cause is uncertain, stop speculative implementation and move to evidence-driven debugging: test one discriminating causal claim at a time, as in `debug`, without duplicating its full procedure here.
5. Do not stack speculative fixes.

Retain independently observed defects; one failed repair does not erase a defect that separate evidence still supports. Reset the diagnosis when repeated attempts based on the same idea stop adding discriminating evidence, rather than after a fixed number of tries.

## Completion

After all slices:

- Review the combined diff for scope and accidental changes.
- Run fresh verification at a scope justified by risk: focused checks for local changes, adjacent checks for shared code, and broad checks for migrations, security, public contracts, or integration readiness.
- Update documentation only when behavior, interfaces, setup, or durable decisions changed.
- Reconcile the final state against the requested scope. For full-spec work, use the complete coverage ledger. For a bounded tranche, report its outcomes and preserve the status of other accepted scope without creating a whole-program ledger; do not close the specification because one tranche finished.
- Do not commit, push, merge, or open a PR unless the user requests it or applicable repository/global instructions delegate it.

Report actual results, including checks not run.

Referenced files: 3

View saved version →

---
name: finish
description: "Finish a development change safely by inspecting the final tree, verifying at the right scope, and performing only the requested Git or PR actions."
---

# Finish

Close the work without turning completion into an automatic merge ritual.

## 1. Inspect final state

Check:

- Current branch and workspace type
- `git status --short`
- Final diff and diff statistics
- Untracked, generated, or temporary files
- Debug logging, TODOs, fixtures, snapshots, or local config accidentally changed
- Secrets or sensitive data
- Whether unrelated user changes are present
- The canonical active path and its callers, including any superseded helper, flag, test, or documentation claim left by the replacement

Do not modify or discard unrelated changes.

When replacement is complete, remove the superseded path in the same change. Retain compatibility only for an evidenced current caller or staged boundary, and name the reason and removal condition; an inert parallel implementation is not a rollback plan.

## 2. Check requirements

Map the final implementation to the requested behavior:

- Completed acceptance criteria
- Intentionally omitted items
- Plan deviations
- Alignment with the applicable authorized goal and current programme
- Compatibility or migration status
- Documentation or setup changes
- Remaining risks

Do this once. Do not reopen accepted design decisions without evidence. Treat implementation deviations as evidence to review, not as authority that settles product meaning. Before integration, require applicable approval for any change to programme order, trust boundaries, or accepted product scope.

## 3. Verify

Use a risk-matched verification ladder:

- Focused regression or behavior checks
- Adjacent suite or build for shared code
- Broad checks for integration, migration, security, or public contracts
- Manual or visual verification where relevant
- Fresh named-host acceptance after the final relevant deployment when the behavior is host-specific

Run checks after the final relevant edit. State exactly what passed and what was not run.

## 4. Review the diff

Perform a compact self-review for:

- Correctness
- Accidental scope
- Data/state consistency
- Error paths
- Compatibility
- Test value
- Avoidable complexity

For high-risk work, one independent reviewer can add value. Verify that reviewer’s findings yourself. Do not require duplicate reviewers for ordinary changes.

## 5. Documentation

Update durable documentation when the change affects:

- Public behavior or APIs
- Setup, configuration, or operations
- Data contracts or migrations
- Architecture decisions another person will need
- User-facing workflows

Do not add changelog noise for invisible local refactors unless repository policy requires it.

## 6. Git and integration

Only commit, push, merge, or create a PR when the user requests that action or applicable repository/global instructions delegate it.

When committing:

- Preserve unrelated user changes.
- Stage intentionally, not with blind `git add .`.
- Use focused commits when it improves review or rollback.
- Follow repository message conventions.

When preparing a PR:

- Identify the correct base branch.
- Summarize behavior and risk.
- Include verification evidence.
- Mention migrations, rollout, screenshots, or follow-up where relevant.

When work remains local, report the branch and workspace path.

## Destructive cleanup

For workspace cleanup, read and apply the Worktree method’s shared removal and authorization contract before acting. From the router use `references/worktree.md`; from the explicit finish leaf use `../worktree/SKILL.md`. Incidental cleanup covers only this workflow’s resources; an explicit request can also select pre-existing worktrees. Present exact targets and actions, protect ignored/local data and current tips, recheck each candidate immediately before removal, and verify preserved refs afterward. Existing authorization for the exact batch is sufficient; do not request it again.

Parking may remove an unmerged checkout while preserving a durable named ref and restoration route. Removing a checkout does not authorize deleting its branch, discarding data, or pruning registrations. Deletion of branches, changes, generated data, or stashes requires explicit authority for that action. Respect active tasks, locks, and the host’s lifecycle; use supported host cleanup for host-managed worktrees. Leave uncertain items pending while completing independent authorized items.

## Completion report

Provide:

- Result
- Main areas changed
- Verification and exact outcomes
- Git/PR state
- Remaining risk or blocked checks

Keep it compact and factual.

Referenced files: 3

View saved version →

---
name: plan
description: "Create an implementation plan sized to settled work. Use when a multi-step change benefits from sequencing, file targets, and explicit verification."
---

# Plan

Create a plan that helps implementation, review, and recovery. Avoid plans that are longer than the work or split one coherent change into dozens of mechanical steps.

## Inputs

Before planning, establish:

- The requested outcome and acceptance criteria
- Relevant repository instructions
- Current implementation and nearby patterns
- Known constraints or decisions
- Verification commands or test locations

Inspect enough code to name realistic touchpoints. Do not invent exact file paths when the repository does not support them.

## Preserve the requested outcome

- Plan the complete usable outcome the user asked for, including necessary end-to-end integration, states, and verification.
- Treat `MVP`, prototype, proof of concept, scaffold, or partial slice as scope choices that require the user or governing specification to make them explicit.
- Use the least complex implementation that covers the full contract. Do not use “minimal” to drop behavior, integrations, or acceptance criteria.
- Order work by real dependencies. Preserve the user's or specification's sequence when it expresses product meaning; record and explain any necessary reorder instead of silently optimizing for the easiest first slice.

## Approved specifications

When an approved specification governs the work:

- Treat it as the authority for scope, settled semantics, and acceptance.
- When planning the full specification, cover its complete accepted scope, even when execution will span phases, PRs, or sessions.
- Keep the current phase or tranche inside that full plan. Never present a partial tranche as the implementation plan for the specification.
- In that full plan, map every normative requirement to a slice and verification outcome, and state every proposed scope or order delta explicitly.
- If the user explicitly requests only a tranche plan, label it `Execution Tranche` and link the applicable specification requirements, dependencies, and existing complete plan. If no complete plan exists, note that absence without creating one by default. Resolve only missing dependencies that block safe planning of this tranche; preserve other requirements without replanning or claiming to deliver them.

Use compact specification IDs or heading anchors rather than repeating the source document.

## Goal authority

- Before a plan changes product meaning, programme order, trust boundaries, or shared infrastructure, identify the applicable current authority and accepted goal.
- A plan may propose and explain a programme or scope delta, but recording the delta does not approve it. Direct current instructions, repository governance, or an explicitly adopted specification may provide the required authority.
- When authority for a material delta is unresolved, keep it as an explicit decision gate and preserve the accepted baseline in every executable slice.

## Choose plan depth

### Inline plan

Use for a moderate change that can be completed in the current session.

Use as few coherent steps as the dependencies need. Each step should produce a meaningful, testable increment.

### Durable plan

Use when:

- The work will span sessions,
- Several subsystems must coordinate,
- A migration or rollout exists,
- Another agent or developer may execute it, or
- The user explicitly requests a plan document.

Store it where the repository expects design or implementation plans. Do not create a new planning directory without checking local conventions.

## Plan structure

Include only what is useful:

1. **Goal and boundaries**
   - Intended behavior
   - Explicit non-goals
   - Material assumptions

2. **Implementation slices**
   - Outcome of the slice
   - Files or areas likely to change
   - Core logic or data-flow change
   - Tests or checks for that slice
   - Dependencies on earlier slices

3. **Cross-cutting concerns**
   - Compatibility or migration
   - Error handling
   - Security/privacy
   - Performance or concurrency
   - Rollback or feature flag, when applicable

4. **Acceptance verification**
   - Targeted tests
   - Broader checks justified by risk
   - Manual or visual verification where automation is not sufficient

## Granularity

A good task is independently understandable and verifiable. Prefer vertical slices over file-by-file chores.

Good:

- Add stale-cursor validation across backend mutation and pagination paths; cover it with regression tests.
- Introduce the new note artifact contract, update producers and consumers, then validate existing fixtures.

Weak:

- Open file A.
- Add import.
- Write ten lines.
- Run tests.
- Commit.

Do not include complete production code in a plan unless a subtle algorithm, schema, or protocol requires a precise example. Pseudocode and data shapes are usually enough.

## Plan review

Review the plan once against the requirements:

- Every acceptance criterion maps to a task or verification step.
- The plan covers the complete requested outcome rather than a scaffold or convenient subset.
- A full-spec plan keeps every accepted requirement visible. An explicitly requested tranche maps its applicable requirements and prerequisites, linking other accepted scope without replanning it.
- Dependencies are ordered correctly.
- Any narrowing, removal, deferral outside the plan, or reordering is an explicit specification delta rather than an implementation convenience.
- No hidden migration or compatibility issue is ignored.
- The plan does not add speculative infrastructure.
- The verification scope matches the risk.

Fix gaps directly. Do not dispatch a separate plan reviewer by default.

## Implementation handoff

When another agent or session will execute the plan, include:

- Current branch or workspace assumptions
- Commands needed to start
- Important files and repository guidance
- Known risks and stopping conditions
- Exact expected final report

Do not paste large source files into the plan.

## Exit behavior

- If the user asked for a plan only, stop after the plan.
- If the user asked for implementation, proceed into coherent, independently verifiable slices without waiting for ritual approval.
- Ask before proceeding only when the plan exposes an unresolved, material product or destructive decision.

Referenced files: 3

View saved version →

---
name: review
description: "Review a diff, commit, branch, PR, or implementation for actionable correctness and risk issues without duplicate reviewer loops or invented findings."
---

# Review

Review the code against its intended behavior and repository reality. Findings come before praise, process narration, or stylistic preference.

## Establish the review target

Determine:

- Diff, commit range, branch, PR, or files in scope
- Requested behavior or acceptance criteria
- Applicable repository instructions
- Relevant tests, schemas, or contracts
- Baseline branch when needed
- The applicable authorized goal and programme authority when the change can reorder work, widen a trust boundary, or introduce generalized infrastructure

Inspect enough surrounding code to understand the change. Do not review a diff in isolation when its correctness depends on state or callers.

## Review priorities

Look for:

1. **Correctness**
   - Wrong state transitions
   - Stale or inconsistent data
   - Edge cases
   - Error handling
   - Partial failure behavior

2. **Data and compatibility**
   - Schema drift
   - Migration safety
   - Backward compatibility
   - Serialization or pagination contracts
   - Idempotency

3. **Security and privacy**
   - Authorization
   - Input validation
   - Secret or sensitive data exposure
   - Injection or unsafe execution
   - Trust-boundary errors

4. **Concurrency and performance**
   - Races
   - Lost updates
   - Unbounded work
   - N+1 behavior
   - Expensive hot paths

5. **Tests and verification**
   - Missing regression coverage
   - Tests that cannot catch the bug
   - Assertions tied to implementation details
   - Unverified platform or migration behavior

6. **Complexity**
   - New abstractions without a present use
   - Duplicate sources of truth
   - Hidden coupling
   - A simpler implementation that reduces risk

Ignore cosmetic style unless it obscures behavior, violates an enforced convention, or creates maintainability risk.

## Goal integrity

When a change could alter product meaning, programme order, trust boundaries, or generalized infrastructure, choose exactly one goal-integrity verdict for each implicated scope. Apply the first matching verdict in this order:

- **authority unclear:** the governing authority or accepted goal cannot be determined from the available evidence.
- **diverges:** authority is known and the change contradicts, displaces, or self-reorders the applicable authorized programme.
- **advances:** authority is known and the change stays within the applicable authorized goal and current programme.
- **research-only:** authority is known and the work is technically useful and compatible with the current programme, but has not been adopted as a product dependency or current programme step.

Agent-authored specifications, decision logs, handoffs, PR descriptions, and implementation commits do not approve themselves. Review implementation quality and goal integrity separately: clean code and green CI can still be `research-only` or `diverges`.

Do not combine verdicts for the same scope. For a mixed change, record separate verdicts for materially different scopes when one label would hide the difference between authorized work and speculative additions. Omit the verdict when the change does not implicate a goal-integrity boundary.

## Validate each finding

Before reporting an issue:

- Identify the exact location.
- Trace the triggering path.
- Check whether existing code or tests already handle it.
- Distinguish a real bug from a hypothetical preference.
- Assess severity based on impact and likelihood.

Do not report speculative concerns as facts.

## Severity

Use:

- **P0:** Immediate data loss, security compromise, or system-wide outage risk.
- **P1:** Likely incorrect behavior, broken contract, serious regression, or blocked release.
- **P2:** Real but bounded defect, fragile behavior, meaningful test gap, or maintainability problem likely to cause errors.

Omit P3-style polish unless the user asks for exhaustive feedback.

## Finding format

For each finding include:

- Severity and concise title
- File and line or symbol
- Triggering condition
- Concrete impact
- Evidence or reasoning
- Smallest credible fix

Keep findings independent and deduplicated.

## Review shape

Perform one integrated review covering requirement compliance and code quality. Do not automatically create separate spec and quality reviewer agents.

A specialist or independent reviewer can be useful for a large, high-risk change. Use at most one by default, and verify its findings yourself before reporting them.

## Output

Start with findings ordered by severity.

Then include, only when useful:

- Goal-integrity verdict, when applicable
- Questions or assumptions
- Verification gaps
- A compact overall assessment

When there are no material findings, say so directly and identify any tests or environments that were not exercised. Do not invent an issue to make the review look substantial.

Referenced files: 3

View saved version →

---
name: review-feedback
description: "Evaluate and act on code-review feedback with technical judgment. Use before applying external suggestions, especially when feedback is ambiguous, broad, or may conflict with repository constraints."
---

# Review Feedback

Treat review feedback as technical input to verify, not commands to obey blindly or social cues to praise.

## Normalize the feedback

Break feedback into independent items. For each item record:

- Requested change
- Claimed problem
- Affected files or behavior
- Whether it is blocking, optional, or unclear
- Any dependency on another item

Do not implement a vague bundle such as “clean this up” without identifying the concrete behavior or quality concern.

## Authority boundary

- Review feedback is technical evidence, not authority by authorship or placement alone. A review comment, PR description, or decision-log edit may propose a scope, order, or trust-boundary change without approving it.
- Direct current instructions from an applicable authorized party, repository governance, or an explicitly adopted specification can authorize such a change. Verify that authority before implementing feedback that changes product meaning, programme order, trust boundaries, or shared infrastructure.
- When feedback exposes a real defect in the current programme, fix the defect within the accepted goal or surface the required decision; do not let the proposed implementation self-authorize a different programme.

## Verify against the repository

For each item:

1. Read the referenced code and surrounding path.
2. Reproduce or trace the claimed issue where practical.
3. Check existing tests and constraints.
4. Look for compatibility, platform, or historical reasons for the current design.
5. Decide whether the proposal solves the real problem with acceptable trade-offs.

Classify the item:

- **Accept:** technically correct and appropriately scoped.
- **Accept with adjustment:** the concern is valid, but the suggested implementation is not the best fit.
- **Verify further:** plausible but evidence is incomplete.
- **Reject:** incorrect, harmful, redundant, or contrary to an explicit decision.
- **Defer:** valid but outside the current change and not release-blocking.

## Ambiguity

Ask for clarification only when the missing answer materially changes behavior or scope and cannot be inferred safely.

Otherwise state the interpretation, choose the safest reversible implementation, and proceed.

## Implementation order

Handle:

1. P0/P1 correctness or security issues
2. Simple independent fixes
3. Deeper refactors or design changes
4. Optional cleanup

Test each meaningful behavior change. Batch tightly related items when separate changes would create temporary inconsistency.

## Pushback

Push back with evidence when:

- The suggestion breaks existing behavior.
- It adds an unused “professional” abstraction.
- The reviewer missed a repository constraint.
- The proposed fix treats a symptom.
- It conflicts with user-approved architecture.
- Its cost or compatibility impact exceeds the demonstrated problem.

State the technical reason and, when possible, offer a narrower alternative.

## Communication

Avoid performative agreement. Useful responses include:

- “Confirmed: this path can return stale state after mutation. I changed X and added Y.”
- “The concern is valid, but the proposed cache invalidation would break Z; I used A instead.”
- “I could not reproduce this under B. The remaining unverified condition is C.”
- “This endpoint has no callers and adding the abstraction would be speculative, so I left it unchanged.”

## Completion

Report each item's disposition and the evidence or change associated with it. Do not claim all feedback is resolved when some items remain unverified or intentionally rejected.

Referenced files: 3

View saved version →

---
name: servotab
description: "Use for hands-on repository work when a quiet, risk-scaled engineering method can improve design, implementation, debugging, review, delegation, workspace lifecycle, or verification. Keep clear local changes direct, preserve the complete requested outcome, and add method only where risk or uncertainty justifies it. Do not use for general technical explanations, simple file lookup, casual discussion, or non-engineering writing."
---

# Servotab

Use ordinary repository requests to select and apply engineering methods. The user need not name a skill. Keep communication quiet; keep the requested outcome complete.

## Before the first consequential action

- Read applicable instructions and the smallest relevant implementation, tests, and accepted contract. Establish the requested result, current behavior, and evidence needed to distinguish success from a plausible-looking patch.
- Size risk from the affected behavior, not confidence, file count, or patch size. Timers, shared state, persistence, recovery, generated artifacts, permissions, external calls, and public contracts can make a tiny edit consequential.
- Preserve explicit corrections and accepted scope. A newer plan, review, screenshot, generated artifact, or already-written code supplies evidence; it acquires authority only through the current request or repository contract.
- When asked to absorb supplied discussions or feedback into the work, cover their material content before choosing implementation focus or dispatching it. Read `references/design.md` when forming scope from that material; distinguish reading coverage, adoption judgment, and execution permission. A first slice must not silently become the whole request.
- Keep clear local work direct. Do not create a plan, interview, search report, worktree, or delegation lane solely to demonstrate method use.
- Choose responsibility before deep execution. Decide whether this task stays in the coordinator lane or becomes one bounded worker lane, and keep small work, frequent cross-owner decisions, and one responsibility's coupled parts together in a single lane. Coupling alone does not force the coordinator lane. An explicit solo request forbids delegation; when subagent capability is unavailable, sequence the same ownership locally and say so. Reuse a worker that already owns the lane instead of duplicating it.

## Resolve decisions at their dependencies

When a material decision remains open, read `references/design.md` before committing to the dependent approach.

- Investigate repository and environmental facts yourself. Ask the user for intent or value choices that materially change the outcome and cannot safely be inferred.
- Ask only questions whose prerequisites are settled; include a grounded recommendation. Recompute dependent choices after an answer changes an assumption. An unresolved branch does not stop independent safe work.
- Use delegated reversible choices and explicit best-effort assumptions where authorized. Do not turn the absence of a prewritten design into a request for approval.
- Stop questioning when the current work is decision-ready. Do not exhaust unrelated future branches or reopen settled product decisions without contradictory evidence.

## Search before new common machinery

Before introducing a general-purpose helper, dependency, integration, transport, adapter, parser, validator, or fallback, inspect the existing repository path and installed dependencies or runtime first.

- Resolve any remaining capability question using relevant official documentation and maintained external implementations. Do not claim a platform limitation from old recollection alone.
- Search only channels that can change the decision. Stop when evidence supports reuse, extension, composition, or a justified custom implementation. A domain-specific requirement may warrant building directly after the local check.
- Report material unavailable coverage accurately. An unavailable channel does not establish that no solution exists.
- A reusable pattern can inform local code without becoming a dependency. Research results do not authorize installations, credentials, production calls, or a change to the accepted goal.

## Load methods at the action they govern

Use the safeguards here directly for clear, bounded work. Load a reference when it resolves material uncertainty, governs a consequential boundary, or is explicitly requested; read it before the dependent action. A task label such as bug fix or completion does not by itself require another document. Reuse an unchanged reference already in context. Combine methods only where each adds a needed decision or check; no fixed full-stack workflow is required.

- Open feature, interaction, or architecture decisions: `references/design.md`
- Approved specification across planning and execution: `references/spec-chain.md`
- Settled multi-step work that needs sequencing: `references/plan.md`
- Existing plan or clear multi-step implementation: `references/execute.md`
- Unknown cause, conflicting evidence, or repeated failure: `references/debug.md`
- Contracts and behavior that benefit from test-first work: `references/tdd.md`
- Diff, commit, branch, PR, or implementation review: `references/review.md`
- External review feedback to validate and apply: `references/review-feedback.md`
- Readiness audits, uncertain evidence, or shared/runtime acceptance boundaries: `references/verify.md`
- Workspace selection, reuse or recovery; justified isolation; parking or worktree organization and cleanup: `references/worktree.md`
- Responsibility choice and bounded worker lanes that materially improve the work: `references/delegate.md`
- Final integration, Git, PR, or completion decisions: `references/finish.md`

Read `references/worktree.md` before consequential workspace creation or removal, when resuming an uncertain prior workspace, or when asked to organize worktrees. Select the intent first: explicit method use and tidying requests do not imply a new checkout or authorize deletion. Reuse suitable task state; do not map workers one-to-one to worktrees. Clear in-place edits need no workspace inventory.

Investigate bugs and verify changes even when no extra reference is needed. Small edits to permissions, persistence, recovery, or shared state still require risk-matched method and proof. Review feedback requires adjudication before editing. Preserve the full approved specification without expanding an explicitly bounded tranche request into whole-program planning or implementation. Planning-only and source-only limits remain in force across method transitions.

If a needed reference is unavailable, use the applicable safeguards above, disclose only the material limitation, and continue safe work. Do not invent its contents or claim it was loaded.

## Preserve outcome and permission boundaries

- Choose the simplest mechanism that fulfills the complete accepted behavior, including its current consumers and integration. Do not silently replace the result with an MVP, placeholder, or backend-only slice.
- Evaluate a proposed mechanism independently while respecting user-selected meaning. Do not widen trust, change programme order, or introduce infrastructure without a current requirement or explicit foundational authorization.
- Keep the existing task record or complete plan current after a material correction. Preserve deferred scope and why it remains. Create a persistent record only when the work needs continuity; do not create a second tracker.
- Stop only at an unresolved authority boundary. Continue other safe, in-scope work. Research, file presence, reviewer advice, and test success confer no additional permission.
- Keep Git operations, deployment, publication, secret access, and paid or live-provider operations within their applicable authorization. No method grants them by itself.

## Choose evidence that could disprove the patch

- A meaningful check distinguishes the relevant failure from success. For a bug, use a reproducer that fails on the old behavior when this can be done safely in a disposable copy; do not revert unrelated live work.
- Inspect the failure families the change actually exposes. A timer needs repeated/interleaved activation; recovery needs interrupted or partial state; an input validator needs malformed inputs; UI motion needs its applicable accessibility behavior. Do not run every family for every edit.
- Do not weaken assertions, drop accepted scenarios, or edit only expected outputs to make a test green. Establish changed requirements before changing the expected result.
- After a check fails, distinguish patch regression, existing baseline failure, and environment failure. Repeated same-mechanism failures require a new causal investigation, not another cosmetic retry.
- When review findings arrive, resolve each material finding as fixed with evidence, rejected with evidence, or explicitly deferred under applicable authority. An open blocker cannot disappear behind a later summary or green CI.

## Close the actual claim

Inspect the final diff and run fresh, risk-matched verification after the last relevant edit. Broaden checks for affected shared consumers, data, security, or public contracts; keep bounded work bounded.

Separate delivered behavior, verified evidence, and remaining gaps. Package validity, installation, instruction delivery, successful use, deployment, and owner acceptance are distinct observations. A hash, checkbox, or configuration entry is not behavior proof.

A real failure may justify a local regression test or a reusable method change. Preserve a small, relevant observation and its causal limit; do not turn every incident into global policy or start an evaluation campaign without authorization.

These instructions guide model behavior. They do not enforce tool permissions or guarantee that the host selected this skill. Use repository tests and host-supported controls for boundaries that require deterministic enforcement.

Referenced files: 15

View saved version →

---
name: spec-chain
description: "Preserve an approved specification through a complete implementation plan and execution. Use for major refactors, migrations, or multi-session work when a confirmed spec is authoritative; keep scope and order changes explicit."
---

# Spec Chain

Preserve an approved specification from planning through execution. The specification defines the required outcome and acceptance contract; the plan defines implementation order and technique.

## Authority

- Treat the accepted specification as the canonical authority for **what** must be implemented, **why** it exists, and **how completion is accepted**.
- Agent-authored specifications, plans, decision logs, handoffs, PR descriptions, and implementation commits are derived material. An agent-authored artifact does not become approved authority merely because it is newer, more detailed, executable, or already implemented; require evidenced applicable approval when it changes programme order, trust boundaries, or product meaning.
- A plan presented as the implementation plan for that specification must cover its entire accepted implementation scope.
- A phase, milestone, or current tranche may subdivide execution, but it may not replace the complete implementation plan or be presented as though it covers the whole specification.
- Keep explicit non-goals excluded. Keep unresolved decisions inside the full plan as decision-closing prerequisites or blockers; do not make them disappear by narrowing the plan.
- Preserve settled semantics such as naming, cardinality, ownership, compatibility, and migration behavior. Implementation convenience is not authority to reopen them.

## Establish the source contract

Before planning or editing, identify:

- Canonical specification path
- Accepted revision or commit
- Approval state and any named open decisions
- Repository baseline the specification was grounded against
- Current implementation state where it may have moved
- Present consumer, current requirement, and authorization provenance when the specification proposes a generalized protocol, new infrastructure, or a programme reorder

Use a stable path plus revision or commit. Do not calculate a hash unless an actual identity or integrity decision needs it.

If several documents contribute requirements, name one primary specification and list the exact normative companions. Do not silently choose whichever document makes the next slice smaller.

If artifacts disagree, resolve their authority rather than using recency or implementation completeness as a proxy for approval. A research implementation may remain valuable evidence while staying outside the accepted product programme.

## Build the complete implementation plan

When the request is for the full specification, create one program-level plan over the full accepted scope. An explicitly bounded tranche request needs only its applicable requirements, dependencies, and stopping point. Link an existing complete plan; if absent, note that fact and resolve only dependencies that block the tranche. Do not expand the request into whole-program planning. Retain the existing status of other requirements; do not replan them or imply they were delivered in this request.

For a full-spec plan:

1. Extract normative requirements, settled decisions, acceptance criteria, migrations, compatibility obligations, and retained non-goals.
2. Refer to existing IDs or headings instead of copying specification prose. When the specification lacks stable identifiers, create compact plan-local IDs tied to its headings.
3. Map every accepted requirement to an implementation slice and verification outcome.
4. Order slices by real dependencies. A different order from the specification is allowed only when the plan records the dependency rationale and preserves the same outcome.
5. Identify the current execution tranche without removing later slices from the program plan.
6. Include decision-closing work before any slice that depends on an unresolved product or destructive choice.

The plan may use several PRs, releases, or sessions. Full coverage does not require a mega-PR.

## Required plan contract

For a full-spec plan, keep the artifact compact and include the sections below. A tranche-only request uses the applicable subset and specification links; it does not need a whole-program coverage ledger or sequence.

### Spec authority

- Canonical path and accepted revision
- Normative companion documents, if any
- Repository baseline and freshness note

### Complete coverage ledger

For each requirement or acceptance ID, record:

- Intended outcome
- Owning implementation slice
- Dependency or decision gate
- Verification evidence
- Status: `planned`, `blocked-decision`, `in-progress`, `implemented`, or `verified`

`planned` may be scheduled later. An accepted requirement cannot be marked out of scope merely because it is outside the current tranche.

### Dependency order

Show the full program sequence or dependency graph. Distinguish definition, enforcement, migration, activation, and deployment when the specification distinguishes them.

### Scope and order deltas

List every proposed `added`, `removed`, `narrowed`, or `reordered` item with:

- Affected specification IDs
- Reason and impact
- Whether it changes product meaning or only implementation technique
- Required decision owner

No entry means no delta. Never hide a scope change inside “minimal,” “first slice,” “later,” or “implementation detail.” Obtain explicit approval before adopting a product or acceptance delta.

### Execution tranches

Name the current tranche and its stopping point. Keep later accepted scope reachable through the specification or existing complete plan. Label a tranche document `Execution Tranche`, not “the implementation plan for the specification.” Link the complete plan when one exists; otherwise link the relevant specification anchors and state the planning boundary.

### Full acceptance

Define completion against the specification coverage ledger, not only the current tranche checklist.

## Execute without losing the specification

At execution entry, read:

- The accepted specification and normative companions
- The complete implementation plan when it exists or the request requires one
- The current execution tranche, when separate
- Current repository instructions and directly affected code/tests

Before editing, check coverage against the requested scope. A full-spec plan must still cover the complete accepted specification. Repair a partial phase plan masquerading as the full plan before relying on that claim; an explicitly bounded tranche needs its applicable requirements and settled dependencies.

During implementation:

- Adapt file paths, internal abstractions, and test mechanics when repository evidence supports the same contract.
- Record any scope, meaning, acceptance, or dependency change as an explicit delta before proceeding.
- Update the coverage ledger as evidence lands.
- Report tranche completion separately from full-spec completion.
- Keep implementation, merge, migration, deployment, and live-state activation as separate authorization gates.

Do not claim the specification is implemented until every accepted coverage item is implemented and verified at the appropriate risk level.

## Token discipline

- Link to specification anchors; do not restate the document.
- Maintain one coverage ledger instead of duplicating requirements across checklists.
- Record deltas only when they exist.
- Do not add separate reviewers, hashes, or ceremonial checkpoints by default.
- Automate coverage checks only when stable IDs and repeated use make the script cheaper than manual reconciliation.

## Regression guard

If a specification settles one public operation over a package of one or many items, a plan may not implement single-item behavior first and defer package cardinality unless the specification is explicitly amended. More generally, an easier subset is not an implementation plan for the whole contract.

Referenced files: 3

View saved version →

---
name: tdd
description: "Apply risk-based test-driven development to bugs, domain logic, state transitions, parsers, contracts, migrations, and behavior where a failing test sharpens the design."
---

# TDD

Use tests as design and evidence. Preserve strict red-green discipline where it pays off, and use lighter verification where the ceremony would add little signal.

## Choose the testing mode

### Strict red-green

Prefer for:

- Bug fixes with a reproducible failure
- Domain rules and calculations
- State machines and mutations
- Parsers, serializers, validators, and data transforms
- API contracts and compatibility behavior
- Migrations
- Concurrency or race-condition fixes
- Security-sensitive behavior

Cycle:

1. Write the smallest behavior-focused test.
2. Execute it once and verify that the failure matches the intended behavioral gap.
3. Implement the minimum coherent change.
4. Run the focused test and confirm it passes.
5. Refactor while keeping it green.
6. Run nearby tests.

### Characterization-first

Use for legacy code whose behavior is poorly documented.

1. Add tests that capture relevant current behavior.
2. Add a failing test for the behavior that must change.
3. Implement the change.
4. Keep unrelated characterized behavior stable.

### Test-alongside

Reasonable for:

- Pure styling and visual polish
- Copy changes
- Simple configuration or wiring
- Generated files
- Small adapters already covered by higher-level tests
- Prototypes or short-lived spikes

Use the most meaningful existing checks. Add automated tests when there is a real regression surface, not to satisfy a quota.

## Existing implementation

Do not delete valid work merely because implementation preceded the test.

When code already exists:

- Reproduce the bug against the current code.
- Add a test that fails on the current behavior when possible.
- If the fix has already been applied, temporarily revert or mutate the narrow change only when safe and efficient to prove the test catches it.
- Otherwise document why red-state proof was impractical and use strong behavior verification.

## Test quality

Prefer tests that:

- Assert externally meaningful behavior
- Fail for one understandable reason
- Are deterministic
- Use real code through stable boundaries
- Survive internal refactoring
- Cover important edge and error paths
- For optional host capabilities, distinguish absence (no doomed action plus useful degradation), rejection, cancellation, policy denial, and success when those are separate observable results

Avoid:

- One test for every trivial function
- Snapshot tests that hide semantic changes
- Mocking the unit under test
- Asserting private implementation details
- Huge fixtures when a focused case works
- Adding sleeps for asynchronous behavior when a condition can be awaited

## Mocks and fakes

Use real collaborators when cheap and deterministic. Mock or fake:

- Network boundaries
- Time
- Randomness
- External services
- Slow or destructive infrastructure

Keep mocks at stable interfaces. If every internal call must be mocked, reconsider coupling.

## Regression proof

For a bug fix, the ideal evidence is:

- Test fails before fix for the expected reason
- Test passes after fix
- Nearby suite remains green

Do not perform risky repository surgery merely to reenact red-green after the fact. Evidence should increase confidence, not damage the workspace.

## Completion checklist

Before claiming test-backed behavior:

- The test targets the requested behavior.
- Failure and success reasons are understood.
- Important boundary cases are represented.
- Focused tests pass after the final relevant change.
- Broader checks were run when risk justifies them.
- Any untested area is stated honestly.

Referenced files: 3

View saved version →

---
name: verify
description: "Verify code or product claims after changes using fresh, risk-matched evidence. Use before saying a bug is fixed, tests pass, requirements are met, or a branch is ready."
---

# Verify

Evidence must support the exact claim. Fresh verification is required after the final relevant change, but verification scope should match risk rather than defaulting blindly to the largest test suite.

## Define the claims

List the claims that matter, such as:

- The original bug no longer reproduces.
- A new behavior matches acceptance criteria.
- Targeted tests pass.
- The module builds or type-checks.
- No existing behavior in the affected area regressed.
- A migration is safe.
- The branch is ready to integrate.

For each claim, identify the command, inspection, or manual scenario that proves it. For decisive cross-boundary probes, name their entry point, relevant path, and material conditions. Freshness and a shared environment do not make a check that bypasses the failing boundary evidence of that boundary's health. A brief coverage note is enough; do not create a second ledger.

## Evidence budget

- Run a check only when its result supports a named claim or can change the next action.
- Do not calculate hashes without an identity or integrity decision that will use them.
- Do not rerun unchanged checks or add a second acceptance loop merely to restate existing proof.
- Stop when every material claim has proportionate fresh evidence; more commands do not automatically create more confidence.

## Evidence maturity without ceremony

Keep capability and effectiveness claims separate:

- A file, rule, tool, or configured capability proves that it exists, not that the task can reach it.
- A reachable route proves wiring, not successful use or delivery.
- A focused exercise or passing test proves current behavior under its observed conditions, not general runtime effectiveness. Keep mechanism repair and whole-user-experience recovery separate; residual symptoms do not automatically invalidate a verified contributing fix.
- A repair verified in the current task proves repair state. Only a later comparable outcome can support a claim that the workflow improved over time.
- Missing observation is `Not verified`, not automatically a defect.

These are claim boundaries, not a required scorecard, ledger, report, or extra review loop.

## Host-boundary evidence ladder

For a host-specific claim, keep these rungs distinct:

1. Source contract
2. Process-level behavior test
3. Built artifact or image identity
4. Activated runtime identity
5. Exact named-host surface
6. Owner-observed behavior

Each rung supports the next investigation step, not the claim above it. Local or dev-browser success is not named-host acceptance; a successful build is not proof that the intended runtime is active; deployment is not owner-observed behavior. After the final relevant change, verify the artifact and activated runtime identities, then obtain fresh acceptance on the exact named host when that is the contract. If the required deployment or owner observation is not authorized or available, mark the higher claim `Not verified`.

## Verification ladder

### Level 1: Focused

Use for local, low-risk changes:

- Regression test
- Affected test file
- Component or module check
- Targeted type-check or lint
- Focused manual interaction

### Level 2: Adjacent

Add when the change touches shared code or several consumers:

- Package or feature suite
- Integration tests around the boundary
- Build for the affected application
- Representative platform or browser check

### Level 3: Broad

Use for high-risk or integration-ready changes:

- Full relevant test suite
- Full build
- Migration dry run
- End-to-end path
- Security or compatibility checks
- Multiple environments when the risk requires it

Do not run Level 3 merely to make a small change look rigorous. Do not stop at Level 1 when shared state, data, security, or public contracts are involved.

## Run and read

For every command:

1. Run it after the final relevant change.
2. Read the complete result needed to assess success.
3. Check exit status, failure counts, warnings, skipped tests, and environment limitations.
4. Record what it actually proves.
5. Do not extrapolate beyond that scope.

A prior run before later edits is stale evidence for the affected behavior.

## Non-test checks

Inspect:

- Final diff and scope
- Untracked or generated files
- Debug output and temporary instrumentation
- Secrets or sensitive data
- Schema and fixture consistency
- Documentation when public behavior or setup changed

For UI work, include a real rendered or interaction check when practical. Unit tests alone may not prove layout or input behavior.

For optional host actions, verify the negative capability path before exposure as well as success. Preserve distinct absent, rejected, cancelled, and policy-denied results when the host distinguishes them; a generic error does not prove correct degradation.

## Regression evidence

For a bug fix, prefer a reproducer or test that would fail under the old behavior. Revert or mutation proof is useful when safe and efficient, but it is not mandatory when it would destabilize the workspace.

## Check the test criterion and close review findings

Before relying on a green result, consider a plausible incorrect implementation that this check would reject. This is a check on the existing evidence, not a mandatory mutation-testing stage or an extra reviewer loop. Schema presence, file signatures, compilation, a mocked success path, and expected-output updates can all miss the behavior being claimed. Use the nearest available behavioral check or full parser where that is the contract. Pair disappearing errors with the intended successful outcome so that suppressing work or bypassing the observed path cannot masquerade as repair. For state-preservation claims, prefer structured comparison or a demonstrably stable normalized before-image over scattered substring checks; retain semantic fields and ordering, and exclude only understood volatile fields. Keep static checks as static evidence.

For timing, ownership, recovery, or optional-host changes, inspect the relevant repeated, interrupted, stale, malformed, denied, or accessibility path. Select from these by the actual changed boundary; this is not an exhaustive test matrix for every task.

Resolve material review findings against the exact final revision. A finding may be fixed and checked, rejected with a concrete counterexample, or explicitly deferred under applicable authority. Record its disposition in the existing review or task surface. CI green or a merge does not itself resolve a reviewer-identified failure. Reproduce disputed findings instead of trusting either the reviewer or implementer by title.

For reusable instructions, distinguish discovery, context delivery, method use, and task outcome. Self-reported loading is supporting evidence only. A static assertion about prompt text cannot establish natural-language activation or improved model behavior.

## Blocked verification

When a check cannot run:

- State the exact reason.
- Separate environmental failure from code failure.
- Run the strongest available alternative.
- Narrow the completion claim.
- Give the command or condition needed to complete verification later.

## Output format

Use three categories:

- **Verified:** claim and evidence
- **Failed:** actual failure and impact
- **Not verified:** omitted or blocked checks and why

Do not say “all tests pass” when only targeted tests ran. Say exactly which tests passed.

Referenced files: 3

View saved version →

---
name: worktree
description: "Choose, reuse, restore, park, or clean up Git workspaces while preserving work and host ownership. Create isolation only when it resolves a real conflict; inspection does not authorize creation or deletion."
---

# Worktree

Choose, resume, and retire repository workspaces without losing work or multiplying unnecessary checkouts. Isolation is one tool; an existing suitable workspace is often enough.

## Start from intent

Explicit use of this method does not request creation or deletion by itself. Match the actual task:

- **Inspect or organize:** inventory relevant workspaces and recommend what to keep, resume, park, or remove. Inspection alone authorizes no mutation.
- **Start or resume:** find the task's existing workspace before creating another. Create only when requested or when a concrete conflict makes isolation useful.
- **Park:** release a paused task's working directory while preserving its work and a usable restoration route. Integration is not required.
- **Finish or clean up:** resolve the named resources under the removal contract below. A request to tidy up is not permission to discard unique work.

Small local edits and read-only workers normally stay in the current workspace. Dirty state, duration, risk, and worker count are signals to inspect, not automatic reasons to create. Identify the actual conflict: unrelated edits, simultaneous writers to the same files or index, incompatible baselines, or an experiment that needs independent verification. Different branch names in one checkout do not separate working files or the index.

## Find the right workspace

Before creating, resuming, or planning cleanup, inspect the current repository and its relevant worktrees; do not scan every repository for an ordinary edit.

- Establish the repository root, common Git directory, current branch or detached HEAD, and whether this is the main checkout, a linked worktree, or a submodule. Resolve paths with Git rather than inferring ownership from directory names.
- Use `git worktree list --porcelain` (with `-z` for machine parsing) and available host/task state to find existing task workspaces, locks, and missing registrations. Deep-inspect only candidates relevant to the request.
- Check the candidate's branch/tip, task purpose, intended integration target, current changes, and known writer or host ownership. Neither an old commit nor absence of a lock proves inactivity.
- Reuse a suitable workspace belonging to this task. Do not take over another active task's checkout. If a prior creation returned ambiguously, inspect Git and host state before retrying; do not manufacture a duplicate.
- Distinguish host-managed, workflow-created, and explicitly user-selected pre-existing resources. Missing host evidence is uncertainty, not evidence of abandonment.

Prefer the host's supported workspace or handoff action for host-managed state. Confirm the actual tool's capabilities; clients may differ in placement, transfer of dirty changes, persistence, and cleanup. Do not manually remove a host-managed worktree behind the host's lifecycle. If the needed host action is unavailable, report that item's limitation and continue independent work.

## Create or restore only the needed state

Before creation, identify the required starting revision and any uncommitted prerequisites. Ordinary `git worktree add` checks out a revision; it does not copy the source checkout's dirty changes. A host transfer may behave differently. Verify the resulting files and tip before continuing the task. Do not silently commit, stash, reset, or copy private environment data to fill a baseline gap; use an authorized transfer or report the missing prerequisite.

When manual Git handling is appropriate:

1. Follow repository naming and location conventions. Prefer an existing ignored `.worktrees/` or `worktrees/` location, or a suitable sibling/user workspace location outside tracked source.
2. Check that a project-local destination is ignored. Do not commit a `.gitignore` edit solely for the workflow without applicable authority.
3. Select an explicit starting revision and descriptive branch, or the existing preserved branch when restoring. Check existing registrations and branch use before adding; do not force-reset a conflicting branch.
4. Avoid placing a worktree inside another linked worktree. If the host explicitly supports nesting, follow its lifecycle contract.
5. Confirm path, branch/tip, required starting content, and ownership from the result. Recheck ambiguous results before another creation attempt.

Separate worktrees isolate files and indexes, not shared refs, ports, databases, services, or output paths. Allocate or sequence those shared resources deliberately when they are used.

Run only necessary setup: use the lockfile's package manager, reuse valid dependencies/caches, and choose a focused baseline that can expose a pre-existing failure. Record relevant baseline failures before editing. Do not reinstall everything by default.

## Decide what can be released

Give each relevant candidate a useful disposition, not just a path listing:

| Disposition | Required reason |
| --- | --- |
| Keep / resume | Active task, needed verification environment, waiting integration, or another concrete retention purpose |
| Park | Paused work has a durable recovery anchor and rebuildable or separately preserved local state |
| Remove | Work is integrated into the correct target, or explicitly discarded, and directory/data checks permit removal |
| Unresolved | Ownership, unique data, recovery, integration, or host state still needs evidence or authority |

Age and count can prompt inspection; neither is a deletion rule. A clean status, merged PR, or successful `worktree remove` is not a complete safety judgment.

For a removal candidate, inspect:

- **Local state:** staged and unstaged changes, untracked files, and ignored content that would disappear with the directory. Use `git status --short --untracked-files=all` and an ignored-file inventory such as `git ls-files --others --ignored --exclude-standard` or a scoped directory listing. Inspect paths and purpose without printing secret values. Ordinary non-force removal can delete ignored files. Rebuildable caches differ from unique databases, notes, recordings, and local config; unknown data stays protected.
- **Hidden tracked state:** before accepting clean-state evidence, inspect index flags at the candidate root with `git ls-files -v` (`-z` for machine parsing). Lowercase tags indicate `assume-unchanged`; `S` or `s` indicates `skip-worktree`. Ordinary status and ignored-file inventories can both miss local edits under these flags, and non-force removal can still discard them. For affected tracked files actually present, compare their content with the index without changing the real index or its flags, accounting for file type and applicable filters; otherwise leave that candidate unresolved. A flag alone proves neither modification nor disposability. Do not automatically clear user flags to simplify inspection. A preserved branch restores committed content, not hidden local edits.
- **Recovery for retained work:** identify a durable named ref that preserves the current tip, plus any separately preserved local state needed to resume. A detached commit or a remembered SHA alone is not a durable anchor; reflog retention is not a parking plan. Do not invent saving work by auto-committing, stashing, uploading, or archiving it. Creating a recovery ref or transferring data must fit the user's authorization. Work explicitly authorized for discard need not be preserved, but permission to remove a directory alone is not permission to discard its unique work.
- **Integration, when claimed:** compare the current tip with the intended target, not merely a PR's past status or the branch's upstream. Ancestry supports ordinary merges; squash/rebase may require commit mapping or review of the actual changes against the target. Tree equality supports only a content comparison at those revisions. A closed PR, stale remote-tracking ref, or failed ancestry test alone cannot settle integration. Report unavailable remote evidence honestly; do not fetch or call remote services without applicable authority.
- **Use and ownership:** check available active-task/process evidence, locks and their reasons, pending merge/rebase/cherry-pick/bisect operations, and submodule state where present. Do not remove an active checkout or bypass an unknown owner. Move the coordinating shell outside a candidate before removing it.

Parking does not need an integration claim: a named branch can preserve unmerged work after its checkout is removed. Preserve that ref, state how to recreate a worktree from it, and identify any environment setup needed. A local ref survives directory removal but is not an off-device backup or protection against later ref deletion.

## Removal and authorization

This is the shared worktree cleanup contract, including cleanup reached through `finish`.

1. Establish scope. Incidental cleanup is limited to resources created and owned by this workflow. An explicit request may also name pre-existing worktrees for management; a familiar path is not ownership.
2. Present exact targets and actions with their reasons and preservation evidence. Removing a working directory, deleting a local branch, deleting a remote branch, discarding changes/data, and pruning registration records are distinct actions. Never bundle them implicitly.
3. Require explicit authorization for destructive actions. Existing authorization covering these exact targets and actions is sufficient; do not ask again. One approval may cover a concrete batch. Broad inspection or tidying language alone is not approval to delete unspecified resources.
4. Immediately before each authorized removal, recheck its tip, local/ignored state, index flags and affected present tracked content, recovery anchor, locks, and ownership. A changed candidate loses its earlier disposition; leave that item pending and proceed with independent unchanged authorized items.
5. Use the supported host action, or ordinary `git worktree remove` for a manually managed linked worktree. A refusal is evidence to investigate. Do not escalate to force, unlock, branch deletion, filesystem deletion, or data loss to complete an old plan. Those actions need their own evidence and authorization.
6. Verify that the intended checkout/registration is gone, preserved refs still resolve to the intended work, and the stated restoration route remains available. Report executed actions separately from recommendations and skipped items.

`git worktree prune` removes stale administrative records, not existing workspaces. A missing path may be moved or on an unmounted device. Inspect lock reasons and storage availability, consider `git worktree repair` for a moved tree, and use `prune --dry-run` to see affected records before seeking or applying exact pruning authority. Never unlock or prune a missing tree just because it looks old.

## Keep continuity useful

Use existing task records or host state when a task spans sessions. Record only what cannot be cheaply reconstructed: purpose, workspace/ref, intended integration target, manager, why it remains, and the next resume step. Refresh observable Git facts when needed. Do not add a global worktree database or a mandatory ledger for tiny work.

Report the selected path and branch/tip, relevant baseline/setup, ownership, and next action. For organization, report concrete dispositions and what was actually done. These instructions guide decisions; they do not provide a deterministic cleanup service or guarantee host behavior.

Referenced files: 3