ClawPatch Bug Discovery Grill Log

Topic

Extend the Harness lifecycle with ClawPatch-backed AFK bug discovery and selected finding resolution.

Initial Situation

Harness already has $debugging-phase, which is a manual, one-bug-at-a-time runtime evidence loop used during E2E/manual validation. It starts from a concrete symptom, reproduction, smoke failure, log, recording, or runtime observation, then uses $debug-agent to prove the cause before patching.

ClawPatch is a different primitive. It maps a repository into semantic feature slices, reviews those slices with an agent provider, persists findings under .clawpatch/, and supports report/show/triage/revalidate plus explicit patch commands. It is useful for long-running AFK discovery, not as a replacement for runtime debugging.

Source Inspection

opensrc path openclaw/clawpatch resolved to:

/Users/stefan/.opensrc/repos/github.com/openclaw/clawpatch/main

Inspected upstream source and docs:

• 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
• docs/validation.md

Relevant upstream behavior:

• Providers include codex, acpx, grok, opencode, pi, mock, and mock-fail.
• ci initializes if needed, maps, reviews, writes a report, and appends a GitHub step summary when configured.
• review and revalidate are read-oriented provider calls.
• fix --finding is explicit and finding-scoped.
• open-pr --patch is explicit and patch-attempt-scoped.
• ClawPatch state is durable under .clawpatch/.
• Review output is schema-validated and evidence-validated against included files.

Pinned Decision Ledger

Q1: Is ClawPatch an extension of $debugging-phase?

Accepted answer:

• No.
• $debugging-phase remains the manual one-bug runtime evidence loop.
• ClawPatch-backed work becomes a new AFK discovery primitive.

Reasoning:

• $debugging-phase is used during E2E tests and manual validation for one concrete bug at a time.
• It involves manual tries, reproduction, inspection, fixing, and verification behavior.
• ClawPatch is meant for long-running AFK flows over many feature slices and likely findings.

Q2: What is the new discovery primitive called?

Accepted answer:

• Create $bug-discovery-phase.

Contract direction:

• $bug-discovery-phase is a goal-compatible, AFK ClawPatch discovery/report/triage wrapper.
• It produces a durable findings ledger, not proven runtime root causes.
• It can recommend follow-up $bug-resolution-phase, $debugging-phase, or debt handling per finding.

Q3: Should ClawPatch discovery patch or open PRs by default?

Accepted answer:

• No.
• $bug-discovery-phase stops at discovery/report/triage by default.
• No automatic clawpatch fix --finding.
• No automatic clawpatch open-pr.
• Fixing requires a separate explicit resolution goal.

Reasoning:

• Discovery can produce many noisy findings.
• Repository mutation needs tighter ownership, acceptance, tests, and review.

Q4: How should Claude/provider cost be handled?

Accepted answer:

• Do not hard-ban Claude.
• Explain cost and billing implications openly in the skill wrapper and docs.
• Generated goals and commands should choose/report an explicit provider.
• If Claude is configured or detected through acpx, pi, Anthropic models, or ANTHROPIC_API_KEY, the phase should warn before AFK execution.

Reasoning:

• The goal is operator transparency, not hidden provider policing.
• Claude through automation may be billed differently from normal Claude Code subscription use.

Q5: Should discovery create tech-debt docs?

Accepted answer:

• No.
• $bug-discovery-phase creates durable ClawPatch state and reports only.
• $bug-resolution-phase creates or updates tech-debt docs after inspecting selected findings.

Reasoning:

• Discovery should stay broad and cheap.
• Resolution has enough inspection depth to decide whether a finding is real debt, false positive, or a bounded fix.

Q6: Should a resolution primitive exist?

Accepted answer:

• Yes.
• Create $bug-resolution-phase.

Contract draft:

• Input: one selected ClawPatch finding, or a tightly bounded batch.
• Inspect ClawPatch finding plus current code.
• Classify each finding as resolve-now, needs-runtime-debugging, tech-debt, false-positive, or blocked.
• For resolve-now, patch with normal Harness/Codex edits, focused tests/checks, and review.
• For needs-runtime-debugging, invoke $debugging-phase.
• For tech-debt, write ClawPatch triage/history plus repo debt/docs artifact through $docs-ingest-phase.
• For false-positive, triage in ClawPatch with a clear reason.
• After patch/debt/triage, run ClawPatch revalidate or update status where appropriate.

Q7: Should $bug-resolution-phase use ClawPatch's patcher?

Accepted answer:

• Use normal Harness/Codex editing by default.
• Use ClawPatch for finding state, context, report linkage, triage/history, dry-run inspection, and revalidation.
• ClawPatch is not the default patching engine.

Reasoning:

• Harness phases already own careful patching, tests, review, notes, and acceptance discipline.
• ClawPatch's patching path is useful, but less aligned with the existing phase lifecycle.

Q8: Are bounded batches allowed?

Accepted answer:

• Yes, but default to one finding.
• Batches are allowed when findings share the same root cause, same owned files, same validation path, or same contract/test gap.

Parallel mode:

• parallel: false: one agent resolves one finding or bounded batch sequentially.
• parallel: true: resolve bounded batch findings in parallel.
• Parallel resolution should use $create-plan and $implement-spec-style ownership hierarchy when proper task decomposition, dependency waves, and worker ownership are needed.
• Workers need explicit file ownership and safe disjointness, or a deliberately shared root-cause patch path.
• Final verification and ClawPatch revalidation stay centralized.

Q9: Should ClawPatch revalidation be required?

Accepted answer:

• Yes.
• When a ClawPatch finding is resolved or marked false-positive, $bug-resolution-phase should revalidate or update the ClawPatch finding state.

Reasoning:

• The finding ledger must remain trustworthy after resolution.

Wiki-Facing Framing

Advertise the normal/manual lifecycle:

1. Run $bug-discovery-phase.
2. Inspect ClawPatch findings.
3. Choose what to resolve.
4. Resolve selected findings through $bug-resolution-phase.

Do not promote an all-in-one "discover and resolve everything" AFK flow as the public default. A single long goal can technically do both only when an operator explicitly asks for it. If automatic resolution is explicitly requested, it should auto-select only high-confidence findings.

Open Branches

• Exact file locations and skill source paths for $bug-discovery-phase and $bug-resolution-phase.
• Exact report naming convention under .clawpatch/reports/.
• Exact repo debt artifact shape consumed by $docs-ingest-phase.
• Whether provider warnings live only in skills/docs or also in CLI scaffold prompts.
• Whether $bug-resolution-phase should support ClawPatch fix --finding --dry-run as an inspection-only option.

Remaining Decisions To Pin

R1: Skill Placement

Recommendation:

• Add source skills under apps/cli/skills/agnostic/debug/bug-discovery-phase and apps/cli/skills/agnostic/debug/bug-resolution-phase.
• Mirror them into .agents/skills/ for this repo's local harness.

Why:

• They are bug lifecycle phases adjacent to the current debug pack.
• They should stay global phase entrypoints, not scoped AGENTS.md primary skills.

R2: Pack Placement

Recommendation:

• Add both phases to the existing debug pack instead of creating a new pack.
• Add clawpatch as a required tool for the debug pack.

Why:

• The current debug pack already distributes $debugging-phase and $debug-agent.
• Discovery/resolution extend the debugging lifecycle without introducing a separate product surface.

R3: Report Naming

Recommendation:

• Default report path: .clawpatch/reports/bug-discovery-<YYYY-MM-DD>-<short-run-id>.md.
• Final phase output must include the exact report path and relevant finding IDs.

Why:

• ClawPatch already owns .clawpatch/reports/.
• A date plus short run id is human-readable and avoids collisions.

R4: Debt Artifact Shape

Recommendation:

• $bug-resolution-phase writes selected larger findings into a repo docs debt ledger under docs/reference/tech-debt/.
• Each entry should link the ClawPatch finding id, report path, source evidence, classification reason, and human-review question.

Why:

• This matches the existing repo pattern of keeping durable operator/reference docs under root docs/.
• $docs-ingest-phase can surface the debt context without pretending speculative future architecture is current truth.

R5: Provider Warning Surface

Recommendation:

• Put provider/cost warning rules in both the phase skills and the CLI scaffold/runbook docs.
• Skill text owns runtime behavior; docs explain operator expectations.

Why:

• The warning matters at execution time and at team onboarding time.

R6: ClawPatch Dry-Run Fix Inspection

Recommendation:

• Allow clawpatch fix --finding <id> --dry-run as optional inspection only.
• Do not use ClawPatch fix as the default patching path.

Why:

• Dry-run can reveal ClawPatch's validation expectation without mutating source.
• Normal Harness edits remain the resolution engine.