Plan: ClawPatch Bug Lifecycle Phases

Generated: 2026-05-22

Initial Situation

Harness already has phase wrappers for requirements, delivery, review, runtime debugging, docs ingest, and debt resolution. $debugging-phase is a manual/runtime-evidence loop for one concrete symptom during E2E checks or validation. ClawPatch is a different primitive: it maps a repository, reviews semantic feature slices, persists .clawpatch/ findings, supports report/show/triage/revalidate, and exposes explicit mutation commands such as fix --finding and open-pr --patch.

The approved spec for IP-170 requires two new global phase skills:

• $bug-discovery-phase: AFK ClawPatch discovery/report/triage, no source mutation by default.
• $bug-resolution-phase: selected finding classification and bounded resolution, patching through normal Harness/Codex edits by default.

The implementation must follow the local write-a-skill architecture: each skill has a concise SKILL.md, optional one-level references for longer details, no speculative scripts unless deterministic repetition proves they are needed, and descriptions that clearly trigger the skill.

Problem

Harness users need long-running ClawPatch discovery without weakening the existing runtime debugging workflow or encouraging expensive, automatic, unbounded patch loops. Scaffold distribution also needs to ship the two phase wrappers consistently, keep phase wrappers out of scoped AGENTS.md primary-skill lines, and expose ClawPatch as a required tool for the bug lifecycle surface.

Solution Shape

Implement the lifecycle as two global phase skills under the phase skill source tree, mirrored into the repo-local agent skill surface. Add ClawPatch to the tool catalog. Extend the debug pack so the new phases travel with existing debugging capabilities. Update prompt filtering so scoped prompts continue excluding all phase wrappers. Add tests for catalog, tool, source-directory, and prompt-filter behavior before changing catalog code. Update docs/wiki to describe the manual lifecycle: discover, inspect, choose, resolve.

Resolved Decision Ledger

Assumptions And Constraints

• Reusable skill source of truth is /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/*.
• Harness sync mirrors those skills into apps/cli/skills/phases/* and .agents/skills/*; .claude/skills symlinks to .agents/skills.
• apps/cli/src/data/catalog/skills.ts, packs.ts, and tools.ts are the bundled scaffold catalog sources.
• apps/cli/src/content/prompts.ts owns phase-wrapper filtering for scoped primary skills.
• Phase wrappers remain global orchestration entrypoints and must not appear in scoped AGENTS.md primary-skill lines.
• Keep implementation surgical. Do not refactor unrelated catalog or prompt rendering.
• The existing unrelated apps/wiki/src/app/(home)/page.tsx diff must be ignored unless the user explicitly scopes it in.

Codebase Findings

• Existing phase skills are sourced in /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/ and mirrored into apps/cli/skills/phases/.
• Existing repo-local phase mirrors are under .agents/skills/.
• Current debug pack contains debugging-phase and debug-agent.
• Current phaseSkillIds omits the new phase names; scoped prompt filtering would leak them until updated.
• toolCatalog includes agent-browser, debug-agent, opensrc, portless, and skills; ClawPatch is not yet represented.
• requiredToolsForSkills derives tools from selected skill requiresTools.
• content.test.ts already verifies pack skill references, skill source directories, required external tools, phase filtering, and debug pack contents.
• There is no docs/runbooks/ directory in the current tree. Operator workflow docs currently live in docs/README.md, docs/reference/*, and routed wiki pages under apps/wiki/content/docs/harness/*.

External Research Used

ClawPatch source inspected through opensrc path openclaw/clawpatch:

• Provider names: codex, acpx, grok, opencode, pi, mock, mock-fail.
• Read-oriented commands: init, map, review, ci, report, show, next, triage, revalidate, doctor, status.
• Explicit mutation commands: fix --finding <id>, open-pr --patch <patchAttemptId>.
• Useful flags: --root, --state-dir, --config, --json, --plain, --limit, --jobs, --feature, --project, --finding, --status, --severity, --provider, --model, --reasoning-effort, --output, --dry-run, --include-dirty.
• report --json returns canonical { total, items, output } plus compatibility aliases.
• State is project-local under .clawpatch/ by default.
• Review and revalidate are intended as read-only; fix is explicit and finding-scoped; open-pr is explicit and patch-attempt-scoped.
• ACPX can route to Claude through --provider acpx --model claude[:model]; this is cost-sensitive and permission-sensitive.

Scoped Skill Routing

Dependency Graph

T1 ──┬── T2 ──┐
     │        ├── T4 ──┬── T5 ──┐
     └── T3 ──┘       ├── T6 ──┼── T8
                      └── T7 ──┘

Parallel Execution Waves

Tasks

T1: Add failing catalog and distribution expectations

• depends_on: []
• location: apps/cli/src/content/content.test.ts, apps/cli/src/data/hooks.test.ts if needed
• description: Add RED tests proving the debug pack includes bug-discovery-phase and bug-resolution-phase, both skills resolve to committed source directories, phaseSkillIds filters them out of scoped primary-skill prompts, and selecting either skill requires the external clawpatch tool. Add a tool-catalog assertion for clawpatch with no dangerous bootstrap command.
• validation: bun test --cwd apps/cli src/content/content.test.ts fails for missing skills/tool/phase filtering before implementation.
• status: Complete
• log: Added RED content-registry expectations and confirmed bun test --cwd apps/cli src/content/content.test.ts fails for missing bug lifecycle skills, ClawPatch tool wiring, and phase filtering.
• files edited/created: apps/cli/src/content/content.test.ts
• backlog_item_id: IP-176
• backlog_item_url: https://linear.app/devpunks/issue/IP-176/scaffold-distributes-clawpatch-bug-lifecycle-phases
• relation_mode: native
• assigned_skills: effect-authoring, effect-best-practices, effect-backend-structure, effect-recoverable-actions, quality-types, simplify, tdd
• tdd_target: A public content-registry test fails because skillsForPack("debug"), requiredToolsForSkills, and scopedPrimarySkills do not yet account for the two new phase skills.
• review_mode: cli

T2: Author $bug-discovery-phase

• depends_on: [T1]
• location: apps/cli/skills/phases/bug-discovery-phase/SKILL.md, apps/cli/skills/phases/bug-discovery-phase/REFERENCE.md, .agents/skills/bug-discovery-phase/SKILL.md, .agents/skills/bug-discovery-phase/REFERENCE.md
• description: Create the discovery skill using write-a-skill structure. Keep SKILL.md compact and triggerable. Put longer ClawPatch command rules, provider warning wording, output contract, and no-mutation boundaries in REFERENCE.md. The skill must record provider/model/scope/limit/jobs/report path, warn on Claude/Anthropic/metred routes, run discovery/report/triage-oriented ClawPatch commands, and stop without fix or open-pr.
• validation: Skill files exist in source and mirror paths; SKILL.md stays under 100 lines; description includes concrete triggers; no script is added unless the task proves deterministic command generation needs one.
• status: Complete
• log: Authored shared bug-discovery-phase skill in wearedevpunks-skills, reviewed command accuracy, synced source into apps/cli/skills/phases and .agents/skills.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-discovery-phase/SKILL.md; /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-discovery-phase/REFERENCE.md; apps/cli/skills/phases/bug-discovery-phase/SKILL.md; apps/cli/skills/phases/bug-discovery-phase/REFERENCE.md; .agents/skills/bug-discovery-phase/SKILL.md; .agents/skills/bug-discovery-phase/REFERENCE.md
• backlog_item_id: IP-171
• backlog_item_url: https://linear.app/devpunks/issue/IP-171/operator-runs-afk-clawpatch-bug-discovery
• relation_mode: native
• assigned_skills: effect-authoring, simplify, write-a-skill, tdd
• tdd_target: The skill-source existence assertion from T1 passes for bug-discovery-phase only after the source directory and mirror are created.
• review_mode: cli

T3: Author $bug-resolution-phase

• depends_on: [T1]
• location: apps/cli/skills/phases/bug-resolution-phase/SKILL.md, apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md, .agents/skills/bug-resolution-phase/SKILL.md, .agents/skills/bug-resolution-phase/REFERENCE.md
• description: Create the resolution skill using write-a-skill structure. Keep SKILL.md compact and put classification matrix, bounded batch rules, parallel ownership rules, ClawPatch revalidation guidance, false-positive triage, and tech-debt routing in REFERENCE.md. The skill must classify findings as resolve-now, needs-runtime-debugging, tech-debt, false-positive, or blocked; use normal Harness/Codex edits for patches; route runtime evidence to $debugging-phase; route debt docs through $docs-ingest-phase; and centralize final verification after parallel work.
• validation: Skill files exist in source and mirror paths; SKILL.md stays under 100 lines; description includes selected finding, ClawPatch finding, bug resolution, and bounded batch triggers.
• status: Complete
• log: Authored shared bug-resolution-phase skill in wearedevpunks-skills, reviewed shape, synced source into apps/cli/skills/phases and .agents/skills.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-resolution-phase/SKILL.md; /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-resolution-phase/REFERENCE.md; apps/cli/skills/phases/bug-resolution-phase/SKILL.md; apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md; .agents/skills/bug-resolution-phase/SKILL.md; .agents/skills/bug-resolution-phase/REFERENCE.md
• backlog_item_id: IP-173
• backlog_item_url: https://linear.app/devpunks/issue/IP-173/operator-resolves-selected-bounded-clawpatch-findings
• relation_mode: native
• assigned_skills: effect-authoring, simplify, write-a-skill, tdd
• tdd_target: The skill-source existence assertion from T1 passes for bug-resolution-phase only after the source directory and mirror are created.
• review_mode: cli

T4: Wire catalog, tool, pack, and scoped prompt filtering

• depends_on: [T2, T3]
• location: apps/cli/src/data/catalog/skills.ts, apps/cli/src/data/catalog/packs.ts, apps/cli/src/data/catalog/tools.ts, apps/cli/src/content/prompts.ts, apps/cli/src/content/content.test.ts, .devpunks/settings.json
• description: Add both skills to the catalog as agnostic phase skills with requiresTools: ["clawpatch"]. Add clawpatch to the tool catalog with required Node/runtime expectations and no automatic provider login/init command. Extend the debug pack to include bug-discovery-phase and bug-resolution-phase next to debugging-phase and debug-agent. Add both names to phaseSkillIds so scoped prompts filter them out. Update the current repo .devpunks/settings.json required tools if scaffold output is kept in sync manually.
• validation: bun test --cwd apps/cli src/content/content.test.ts; bun run --cwd apps/cli check; bun run check:repo if formatting touches root-tracked docs/manifests.
• status: Complete
• log: Wired both skills into the CLI content catalog, debug pack, ClawPatch tool catalog, phase-skill filtering, and .devpunks/settings.json. bun test --cwd apps/cli src/content/content.test.ts passes.
• files edited/created: apps/cli/src/data/catalog/skills.ts; apps/cli/src/data/catalog/packs.ts; apps/cli/src/data/catalog/tools.ts; apps/cli/src/content/prompts.ts; .devpunks/settings.json
• backlog_item_id: IP-176
• backlog_item_url: https://linear.app/devpunks/issue/IP-176/scaffold-distributes-clawpatch-bug-lifecycle-phases
• relation_mode: native
• assigned_skills: effect-authoring, effect-best-practices, effect-backend-structure, effect-recoverable-actions, quality-types, simplify, tdd
• tdd_target: The public content-registry tests from T1 turn green without weakening phase-skill filtering for scoped prompts.
• review_mode: cli

T5: Document the lifecycle in routed wiki and root docs

• depends_on: [T4]
• location: apps/wiki/content/docs/harness/skills-and-packs/phase-wrappers.mdx, apps/wiki/content/docs/harness/execution-modes/goal-mode-and-afk.mdx, apps/wiki/content/docs/harness/lifecycle-flows/*.mdx, apps/wiki/content/docs/harness/lifecycle-flows/meta.json, apps/wiki/content/docs/harness/validation-and-tools/external-tool-contract.mdx, apps/wiki/index.md, apps/wiki/log.md, docs/README.md, docs/reference/harness-intelligence.md, docs/clawpatch-bug-discovery-grill-status.md
• description: Add wiki-facing docs for discover, inspect, choose, resolve. Update phase-wrapper inventory, AFK goal-mode inventory, external tool contract, and lifecycle navigation. Keep all-in-one discover-and-resolve out of the default story. Add provider/cost warning language in docs. Update root docs and grill status to point to the implemented skill/spec/plan lifecycle.
• validation: bun run --cwd apps/wiki check if available; otherwise bun run check:repo plus manual link/path inspection for changed markdown/MDX files.
• status: Complete
• log: Added the routed ClawPatch bug lifecycle docs, phase/tool/root docs updates, and wiki bookkeeping. Worker-reported focused formatting passed for owned docs; root check:repo still has unrelated formatting drift outside this task.
• files edited/created: apps/wiki/content/docs/harness/lifecycle-flows/clawpatch-bug-lifecycle.mdx; apps/wiki/content/docs/harness/lifecycle-flows/meta.json; apps/wiki/content/docs/harness/skills-and-packs/phase-wrappers.mdx; apps/wiki/content/docs/harness/execution-modes/goal-mode-and-afk.mdx; apps/wiki/content/docs/harness/validation-and-tools/external-tool-contract.mdx; apps/wiki/index.md; apps/wiki/log.md; docs/README.md; docs/reference/harness-intelligence.md
• backlog_item_id: IP-172
• backlog_item_url: https://linear.app/devpunks/issue/IP-172/operator-reviews-and-routes-clawpatch-findings
• relation_mode: native
• assigned_skills: parallel-research, simplify
• tdd_target: A docs/navigation check or manual MDX inspection proves the new lifecycle page is linked from meta.json and does not describe all-in-one resolution as the default.
• review_mode: cli

T6: Encode tech-debt routing guidance

• depends_on: [T4]
• location: apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md, .agents/skills/bug-resolution-phase/REFERENCE.md, apps/wiki/content/docs/harness/lifecycle-flows/*.mdx, docs/reference/harness-intelligence.md
• description: Ensure resolution guidance covers tech-debt behavior deeply enough for executor safety. Tech-debt findings create or update durable debt/docs context only after selected-finding classification and preserve finding ID, report path, evidence, classification reason, and human-review question. Discovery must not create repo debt docs. Docs ingest must not present speculative architecture as current truth.
• validation: Manual acceptance audit against IP-175 acceptance signals; bun run check:repo for markdown formatting.
• status: Complete
• log: Tightened bug-resolution-phase reference guidance for selected-finding tech-debt routing, required debt artifact fields, and avoiding speculative architecture-as-current-truth. Mirrored shared skill updates into CLI and .agents.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-resolution-phase/REFERENCE.md; apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md; .agents/skills/bug-resolution-phase/REFERENCE.md
• backlog_item_id: IP-175
• backlog_item_url: https://linear.app/devpunks/issue/IP-175/larger-clawpatch-findings-become-durable-tech-debt-context
• relation_mode: native
• assigned_skills: parallel-research, simplify, write-a-skill
• tdd_target: The resolution reference contains an explicit selected-finding tech-debt gate and required artifact fields that can be checked by text assertions or manual acceptance audit.
• review_mode: cli

T7: Encode bounded parallel-resolution guidance

• depends_on: [T4]
• location: apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md, .agents/skills/bug-resolution-phase/REFERENCE.md, apps/wiki/content/docs/harness/execution-modes/sequential-and-parallel-delivery.mdx, apps/wiki/content/docs/harness/lifecycle-flows/*.mdx, docs/reference/harness-intelligence.md
• description: Ensure resolution guidance covers parallel: true behavior deeply enough for executor safety. Parallel batches require shared root cause/files/validation/contract gap, explicit ownership, $create-plan/$implement-spec-style waves when needed, and centralized final verification/revalidation. Worker scopes must be disjoint or intentionally shared around one root-cause patch.
• validation: Manual acceptance audit against IP-174 acceptance signals; bun run check:repo for markdown formatting.
• status: Complete
• log: Tightened bug-resolution-phase reference guidance for bounded parallel batches, worker edit boundaries, central ClawPatch status ownership, and pausing fan-out when findings converge on one root-cause patch.
• files edited/created: /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/bug-resolution-phase/REFERENCE.md; apps/cli/skills/phases/bug-resolution-phase/REFERENCE.md; .agents/skills/bug-resolution-phase/REFERENCE.md
• backlog_item_id: IP-174
• backlog_item_url: https://linear.app/devpunks/issue/IP-174/operator-resolves-bounded-finding-batches-in-parallel
• relation_mode: native
• assigned_skills: parallel-research, simplify, write-a-skill
• tdd_target: The resolution reference contains an explicit bounded-batch gate and centralized revalidation gate that can be checked by text assertions or manual acceptance audit.
• review_mode: cli

T8: Final validation, baseline proof, and tracker sync

• depends_on: [T5, T6, T7]
• location: apps/cli, apps/wiki, docs, apps/wiki/content/docs/project/specs/cli/IP-170-clawpatch-bug-lifecycle/IMPLEMENTATION-NOTES.md, Linear IP-170 through IP-176
• description: Run focused CLI tests, full CLI check, root formatting/checks as feasible, and build/baseline proof if catalog distribution requires it. Add implementation notes with acceptance audit, validation evidence, docs ingest outcome, and manual review checklist. Sync Linear with a concise comment or links to spec/plan/implementation notes without rewriting product-facing story bodies.
• validation: Minimum: bun test --cwd apps/cli src/content/content.test.ts, bun run --cwd apps/cli check, bun run check:repo. If catalog/baseline artifacts changed: bun run baseline:build. Final status reports any skipped validation with reason.
• status: Complete
• log: Ran focused CLI tests, CLI check, wiki check, targeted formatting, and root check:repo. Root check:repo remains blocked by unrelated .tmp/landing-cli-proof/** formatting drift; owned files pass focused formatting and app checks. Added implementation notes, acceptance audit, manual checklist, spec finalization, and Linear implementation comment.
• files edited/created: apps/wiki/content/docs/project/specs/cli/IP-170-clawpatch-bug-lifecycle/IMPLEMENTATION-NOTES.md; apps/wiki/content/docs/project/specs/cli/IP-170-clawpatch-bug-lifecycle/SPEC.md; apps/wiki/content/docs/project/specs/cli/IP-170-clawpatch-bug-lifecycle/PLAN.md; apps/wiki/content/docs/project/specs/cli/cli-specs.md; apps/wiki/index.md; apps/wiki/log.md; docs/clawpatch-bug-discovery-grill-status.md
• backlog_item_id: IP-170
• backlog_item_url: https://linear.app/devpunks/issue/IP-170/clawpatch-backed-bug-discovery-and-resolution-phases
• relation_mode: native
• assigned_skills: effect-authoring, quality-types, parallel-research, simplify, tdd
• tdd_target: Final acceptance audit proves every IP-170 child story has either passing test evidence, docs evidence, or explicit implementation-note evidence.
• review_mode: cli

Testing Strategy

• Start with T1 RED tests for public scaffold/content behavior.
• Use focused CLI tests while wiring catalog behavior: bun test --cwd apps/cli src/content/content.test.ts.
• Use bun run --cwd apps/cli check after catalog and skill-source changes.
• Use bun run check:repo after markdown/docs and root tracked files change.
• Use bun run baseline:build only if implementation updates checked-in baseline output or release artifacts.
• Do not run live ClawPatch against this repo as part of implementation validation unless the user explicitly asks. The feature being built is Harness guidance/distribution, not a live discovery run.

Risks And Mitigations

• Risk: New phase wrappers leak into scoped AGENTS.md primary skills. Mitigation: Add phaseSkillIds tests before wiring catalog.
• Risk: Skills become too long and hard to trigger. Mitigation: Follow write-a-skill; keep SKILL.md concise and move command detail to REFERENCE.md.
• Risk: ClawPatch provider guidance implies Claude is banned. Mitigation: Wording must warn and preserve operator choice.
• Risk: Discovery docs imply findings are proven bugs. Mitigation: Repeat finding-ledger vs runtime-root-cause boundary in skill output contracts and wiki docs.
• Risk: Parallel resolution encourages unrelated mutation. Mitigation: Skill requires bounded batch gate, explicit ownership, and centralized verification.
• Risk: Current repo generated state drifts from bundled catalog. Mitigation: Update .devpunks/settings.json and mirrors deliberately, then validate catalog tests.

Validation Gates

1. Skill shape gate: Both new skills have compact SKILL.md, reference files where needed, triggerable descriptions, and no unnecessary scripts.
2. Catalog gate: Debug pack, skill catalog, tool catalog, required tools, and phase filtering tests pass.
3. Docs gate: Wiki/root docs describe the manual lifecycle and cost warning without promoting automatic resolution.
4. Parallel/debt gate: Resolution guidance covers bounded batches, ownership, tech-debt artifact data, and centralized revalidation.
5. Closeout gate: Implementation notes record acceptance audit, validation commands, skipped checks if any, and Linear sync.

Backlog Sync Plan

• Keep IP-170 as the parent epic and IP-171 through IP-176 as product-facing stories.
• Do not create task-level Linear issues.
• After implementation, add a single IP-170 comment linking the spec, plan, and implementation notes.
• Close or update child stories only after their acceptance evidence is present in implementation notes.

Unresolved Questions

None blocking. If implementation discovers a missing deterministic script need for ClawPatch command assembly, add it only after proving repeated manual command construction is error-prone.