Spec: ClawPatch Bug Lifecycle Phases

User Input

lets now create the two skills with the pinned decisions [$create-spec](/Users/stefan/Desktop/repos/harness-intelligence/.agents/skills/create-spec/SKILL.md) for [https://linear.app/devpunks/issue/IP-170/clawpatch-backed-bug-discovery-and-resolution-phases](https://linear.app/devpunks/issue/IP-170/clawpatch-backed-bug-discovery-and-resolution-phases) https://linear.app/devpunks/issue/IP-173/operator-resolves-selected-bounded-clawpatch-findings https://linear.app/devpunks/issue/IP-171/operator-runs-afk-clawpatch-bug-discovery https://linear.app/devpunks/issue/IP-176/scaffold-distributes-clawpatch-bug-lifecycle-phases https://linear.app/devpunks/issue/IP-175/larger-clawpatch-findings-become-durable-tech-debt-context https://linear.app/devpunks/issue/IP-174/operator-resolves-bounded-finding-batches-in-parallel https://linear.app/devpunks/issue/IP-172/operator-reviews-and-routes-clawpatch-findings

Relevant pinned decisions:

• $debugging-phase remains the manual, one-bug-at-a-time runtime/E2E evidence loop.
• ClawPatch-backed work gets a new $bug-discovery-phase; it is not folded into $debugging-phase.
• $bug-discovery-phase is AFK and goal-compatible.
• $bug-discovery-phase produces durable ClawPatch state and reports, not proven root causes.
• $bug-discovery-phase stops at discovery/report/triage by default.
• $bug-discovery-phase does not run clawpatch fix --finding or clawpatch open-pr by default.
• Claude is allowed as a provider route; Harness should warn transparently about AFK cost/billing implications instead of banning it.
• Generated ClawPatch goals/commands should make the selected provider explicit.
• $bug-discovery-phase does not create repo tech-debt docs.
• Create $bug-resolution-phase for selected ClawPatch finding resolution.
• $bug-resolution-phase can take one finding or a tightly bounded batch.
• $bug-resolution-phase classifies findings as resolve-now, needs-runtime-debugging, tech-debt, false-positive, or blocked.
• resolve-now patches use normal Harness/Codex edits by default.
• ClawPatch is used for finding context, state, triage/history, report linkage, dry-run inspection if useful, and revalidation.
• ClawPatch is not the default patching engine.
• needs-runtime-debugging routes into $debugging-phase.
• tech-debt writes ClawPatch triage/history plus repo debt/docs through $docs-ingest-phase.
• False positives are triaged in ClawPatch with a clear reason.
• Revalidate or update ClawPatch status after resolution or false-positive classification.
• Default resolution scope is one finding.
• Bounded batches are allowed when findings share root cause, owned files, validation path, or contract/test gap.
• parallel: true in $bug-resolution-phase resolves bounded batch findings in parallel, not only inspecting them.
• Parallel resolution should use $create-plan and $implement-spec-style ownership hierarchy when decomposition, waves, and worker ownership are needed.
• Final verification and ClawPatch revalidation remain centralized after parallel work.
• Wiki-facing docs advertise the manual lifecycle: discover, inspect, choose, resolve.
• Wiki-facing docs do not promote all-in-one discover-and-resolve as the default story.
• If an all-in-one flow is explicitly requested, automatic resolution should select only high-confidence findings.

Context

Harness currently has $debugging-phase for manual, evidence-backed bug fixing during E2E tests and runtime validation. That phase starts from a concrete symptom and proves a root cause through repros, logs, recordings, failing tests, or other runtime evidence before patching.

ClawPatch adds a different lifecycle need. It can map a repository into semantic slices, review those slices through a configured agent provider, persist findings under .clawpatch/, and support report, triage, revalidation, and explicit patch commands. Harness needs this as an AFK discovery and selected-resolution flow without diluting the existing runtime debugging contract.

The affected operators are CLI/Harness users who want long-running bug discovery, triageable finding ledgers, and bounded follow-up resolution without turning every ClawPatch finding into a patch, PR, or tech-debt artifact automatically.

Non-Goals

• Replacing $debugging-phase or $debug-agent.
• Treating ClawPatch findings as proven runtime root causes.
• Running clawpatch fix --finding during discovery by default.
• Running clawpatch open-pr during discovery by default.
• Using ClawPatch as the default patching engine for resolution.
• Resolving every reported finding automatically.
• Turning every discovery finding into backlog scope or durable tech debt.
• Advertising all-in-one discover-and-resolve as the default wiki-facing workflow.
• Creating a separate public product surface for ClawPatch.
• Performing broad product, architecture, or platform redesign inside $bug-resolution-phase.

Acceptance Criteria

• Harness exposes $bug-discovery-phase as a global phase entrypoint for long-running ClawPatch discovery, reporting, and triage.
• $bug-discovery-phase records the selected provider, model, scope, --limit, --jobs, and report path before running.
• $bug-discovery-phase warns when Claude, Anthropic, or likely metered API routes are configured, while still allowing the operator to choose that route.
• $bug-discovery-phase makes the selected ClawPatch provider explicit in generated goals, commands, and final output.
• $bug-discovery-phase can run ClawPatch discovery, report, and triage-oriented commands without mutating source files.
• $bug-discovery-phase final output includes the ClawPatch report path, durable ledger location, relevant finding IDs, and a clear statement that findings are not proven runtime root causes.
• $bug-discovery-phase does not create repo tech-debt docs during broad discovery.
• Discovery output recommends follow-up routing for findings without resolving them automatically.
• Findings can be routed to $bug-resolution-phase, $debugging-phase, tech-debt handling, false-positive triage, or blocked status.
• Wiki-facing guidance presents the normal lifecycle as discover, inspect, choose, resolve.
• Wiki-facing guidance does not promote all-in-one discover-and-resolve as the default public story.
• Harness exposes $bug-resolution-phase as a global phase entrypoint for one selected ClawPatch finding by default.
• $bug-resolution-phase accepts a tightly bounded batch only when findings share root cause, owned files, validation path, or contract/test gap.
• $bug-resolution-phase classifies each selected finding as resolve-now, needs-runtime-debugging, tech-debt, false-positive, or blocked.
• resolve-now findings are patched through normal Harness/Codex edits by default.
• $bug-resolution-phase uses ClawPatch for finding context, report linkage, triage/history, optional dry-run inspection, and revalidation.
• needs-runtime-debugging findings route into $debugging-phase.
• false-positive findings are triaged in ClawPatch with a clear reason.
• tech-debt findings create or update durable repo debt/docs context only after selected-finding classification.
• Tech-debt artifacts preserve the ClawPatch finding ID, report path, source evidence, classification reason, and human-review question.
• $docs-ingest-phase surfaces docs-affecting debt context without presenting speculative future architecture as current truth.
• Resolved or false-positive findings are revalidated through ClawPatch or have their ClawPatch status updated.
• parallel: true in $bug-resolution-phase resolves bounded batch findings in parallel, rather than only inspecting them.
• Parallel resolution scopes make file ownership and safe disjointness explicit, or document the intentionally shared root-cause patch path.
• Parallel resolution uses $create-plan and $implement-spec-style ownership hierarchy when decomposition, dependency waves, or worker ownership are needed.
• Final verification and ClawPatch revalidation remain centralized after parallel resolution work.
• Scaffold/update distributes $bug-discovery-phase and $bug-resolution-phase consistently with the existing phase-wrapper model.
• Scoped AGENTS.md primary-skill lines do not list $bug-discovery-phase or $bug-resolution-phase.
• ClawPatch is represented as a required tool for the selected pack or lifecycle surface that owns bug discovery and resolution.
• Provider and cost warning guidance appears in the phase skills and operator-facing docs.
• Root docs and wiki lifecycle pages describe the manual discover, inspect, choose, resolve flow.
• If an operator explicitly asks for a single all-in-one discover-and-resolve goal, automatic resolution selects only high-confidence findings.

Constraints

• Keep phase wrappers as global orchestration entrypoints, not scoped prompt primary skills.
• Preserve the existing $debugging-phase contract for runtime symptom, reproduction, root-cause proof, patch, and regression validation.
• Keep discovery read-oriented against source files by default.
• Keep mutation inside explicit selected-resolution work.
• Keep provider choice transparent; warn about cost risk without banning Claude, Anthropic, or metered routes.
• Keep ClawPatch report and triage state durable enough for later resolution goals.
• Keep final verification centralized after parallel workers.
• Keep docs technical and source-faithful; ClawPatch findings must not be written as current product truth until verified or classified as debt.

Technical Notes

• Source decisions live in docs/clawpatch-bug-discovery-grill-log.md and docs/clawpatch-bug-discovery-grill-status.md.
• ClawPatch source inspection used opensrc path openclaw/clawpatch.
• Inspected upstream files included README.md, src/provider.ts, src/app.ts, src/cli.ts, src/prompt.ts, src/review-validation.ts, docs/providers.md, docs/safety.md, docs/patching.md, and docs/validation.md.
• Relevant upstream provider names include codex, acpx, grok, opencode, pi, mock, and mock-fail.
• Relevant upstream commands include ci, review, report, triage, show, revalidate, fix --finding, and open-pr --patch.
• Existing phase-wrapper guidance says phase skills remain parent-level orchestration and stay out of scoped AGENTS.md primary-skill lists.

Decision Log