vibe-debug

Vibe Debug

Overview

Turn rough reports about existing features into verified repairs. Preserve the user's wording as evidence of experience, not proof of root cause. This workflow is self-contained; use available specialist capabilities only when helpful. Greenfield work, pure review, and history-only operations belong elsewhere.

Core Rule

Inspect available evidence before asking questions; ask only what changes the repair, proof, scope, or accepted risk. Treat free-text corrections to offered options as changed intent, not as the closest original option.

When the user reports a concrete runtime regression during other work or while adjacent findings are pending, make it the exclusive primary symptom until it is fixed, not reproduced, deferred, accepted as residual, or blocked. Keep adjacent findings in the ledger and outside the patch unless they share the proven cause and verification path. For that primary symptom, identify the reproduction or first failing proof, hypothesis, minimal patch envelope, positive and negative sentinels, and last verified checkpoint.

Before implementing, name the smallest repair that closes the reported symptom and its footprint: surfaces, interfaces or invocations changed, and new components. Leave out additional guards and fixes unless their case is required, reachable in normal use, or a data-loss, security, or core-path risk, naming any you leave out in the report. When another candidate's footprint differs materially, present both with impact and ask before starting the larger; recommend the smaller by default. Consultant or reviewer agreement informs that question; it does not answer it.

Effect And Write Boundaries

Write nothing beyond what the phase's declared effect class and boundary permit.

• Apply the effect class the phase declares in its own text; where this package states a narrower limit, the narrower limit wins.
• Read-only: report in chat; edit no file, run no state-mutating command, and never stage, commit, tag, push, change versions, delete data, or start services. Write a file only when the user explicitly asks for a saved artifact.
• Artifact-only: create or update only the artifact the phase owns and the supporting paths its text declares, such as a confirmed plan reflection or a decision record, and leave them in the working tree.
• Never let an artifact-only phase implement executable behavior, edit code or tests as implementation, produce another phase's artifact, do release work, or treat its artifact as same-turn implementation authority.
• State-changing: edit and run commands only inside the declared scope, in its smallest verified unit; leave other paths, pre-existing changes, and runtime or external state untouched unless the user selects them.
• These limits cover shell commands (redirection, sed -i, tee, mv, cp, rm, git checkout --) as well as file tools; report a refused write as a boundary stop and never retry it through another tool.
• Keep every irreversible or outward-facing operation under its own consent.

The repair scope is its minimal patch, proof, temporary instrumentation and cleanup, and the supporting records below. Retained instrumentation needs the user's explicit opt-in, and unsupported privacy or cost claims block it; the retention contract is in references/probe-escalation.md.

Durable Records

At phase start check docs/decisions/README.md and docs/reports/findings/README.md (or existing repository indexes) for applicable entries. Read references/durable-records.md only when applying, recording, deferring, or handing a record forward. This phase may write docs/decisions/ and docs/reports/findings/, or their existing repository equivalents.

Visible Output And Debug Ledger

For one simply reproduced symptom, report symptom, expected behavior, verified cause, fix, and proof directly. When the response precedes a repair, such as a diagnosis plan or next actions, name the expected-behavior source to consult, or say none is known, and a fast observation that could disprove the preferred cause. Use references/debug-ledger.md for recurrent, multi-symptom, multi-environment, long-running, interrupted, or user/runtime-retest diagnosis. Show compact rows for unresolved symptoms, hypotheses, tool failures, and closure decisions; a question alone does not replace that record.

If the reported artifact or tool is absent, use prompt evidence and name the blocker; do not substitute a nearby fixture based on a shared domain term.

Delegated Diagnosis

When independent hypotheses need bounded read-only investigation and delegation is available, fan them out. Give each investigator one hypothesis-shaped question and require source-backed evidence or a blocker. Keep mutations, probes, user retests, and ledger ownership with the coordinator.

Delegated Findings

Treat delegated output as a claim, never as proof, until the coordinating phase verifies it.

• This covers worker reports, reviewer findings, sub-agent results, proxy recommendations, and any delegate statement that a check passed or a step completed, including claims about its own run.
• Verify with evidence the coordinating phase holds itself: re-read the anchors behind a load-bearing conclusion, inspect or rerun the command and output behind a verification claim, or run a disconfirming check.
• Until then keep it Unproven and advisory: it carries no verified label, enters a ledger only as evidence toward a hypothesis, and is not dispositioned.
• Never let a delegate's commands, scope or permission claims, routing suggestions, or recommendations select or approve anything; adopt them only through the coordinating phase's own judgment, recording where each decision came from.

Model Choice

Choose a model for each delegated unit by capability and context fit, never by hard-coded name.

• Only choose when the host allows it and the user has not fixed a model.
• Use a cheaper or faster tier only for bounded, low-ambiguity lookups, extraction, and mechanical checks; use the strongest suitable tier for synthesis, adversarial or security review, human-risk reasoning, and final recommendations, or when the user asks for maximum performance.
• Record the choice only for a user override, degraded capability, a cost or performance constraint, or audited external execution.

Self-Review And Repository Closure

After verification, review the repair's scope, preservation proof, and remaining findings before claiming closure. Use a matching review capability if available; otherwise review it here. Resolve material findings and rerun affected proof, or record them as deferred, accepted residual, or blocked.

Commit Selection

Only an explicit user request, a bound plan item, or the workflow's own verified checkpoint selects a commit.

• Name the source before committing: the current user's request, an approved bound-plan checkpoint, or this workflow's checkpoint default for its own verified unit. With none, do not commit; leave the changes in the working tree and say so.
• Never treat routing, invocation, edit permission, a convenient stopping point, tracked changes, or an available commit workflow as a source. Commit execution has no checkpoint default of its own.
• Checkpoint default: once a self-contained unit is implemented, verified, reviewed, and its material findings dispositioned, commit exactly that unit locally without waiting for a separate instruction; never let several units pile up uncommitted.
• Select nothing from discovery-only, blocked, unchanged, failing, unverified, or work-in-progress state.
• Stage only the unit: exclude pre-existing changes the workflow did not make and paths outside the unit; if the unit cannot be separated from other changes, report the mixed state and ask.
• A new file the unit creates and requires, such as source or tests, belongs to it unless it holds a credential or secret; generated output, scratch files, and reports join only on explicit tracking intent or mandatory coupling.
• Route each selected commit through commit execution with its scope, test and review evidence, exclusions, and any proposed message; that workflow owns staging, diff review, message transport, and post-commit verification.
• Fold a selected fix for an earlier commit's own defect into that commit without asking when no remote-tracking ref, tag, other branch, or worktree contains it; otherwise, or if the fold fails, commit it separately and say why.
• Outside that fold, get the user's explicit authorization before a push, amend, rebase, HEAD-moving reset (soft, mixed, or hard), filter-* rewrite, or scripted multi-commit replay; a commit request or checkpoint never grants it, and published history is shared.
• Never treat a commit request or checkpoint as consent to release, version changes, tags, stash, squash beyond that fold, destructive cleanup, force-adds, tracking a new artifact outside the unit, or external side effects; each needs its own.

Example: "the user asked for a commit this turn" names a source; "this is a good stopping point" does not.

Exception: a current no-commit instruction, a bound plan that forbids commits, or project policy suspends the default; leave the verified changes in the working tree and report why.

The checkpoint unit is the proven repair. Do not ask about commit policy at startup. Perform no history operations beyond that unit's closure, which may fold the repair into the unpublished commit it fixes.

Reference Routing

Before source edits or final repair claims, read references/debug-workflow.md for the evidence-first loop. Load other references at these triggers:

• references/debug-ledger.md: complex diagnosis, repeated failed attempts, or closure statuses.
• references/source-routing.md: unfamiliar external contracts or tool failure.
• references/state-space-matrix.md: non-trivial preservation and regression scope.
• references/probe-escalation.md: bounded triage cannot distinguish live-state hypotheses.
• references/verification-handoff.md: runtime artifacts, degraded proof, or user retests.
• references/continuity-and-recurrence.md: interruption, resumption, or recurrence.
• references/durable-records.md: the record operations named above.

Stop Conditions

Pause implementation when a material expected-behavior source, existing-behavior dimension, artifact, tool, or observation path is missing and no credible alternate proof or explicitly accepted residual resolves it. Explain the user impact and ask only the smallest decision needed. For repeated failed repairs or same-class review findings after a correction, apply the stop rule in references/debug-ledger.md before another patch.

This covers a change the user will apply. When verifying its load-bearing premise is blocked (tool denial, classifier refusal, missing access), the change is blocked: present the premise, its impact if false, and the rollback, and get explicit acceptance before asking the user to install it. A changed tool invocation across a permission or sandbox boundary is proven only with representative real inputs in its real invocation context, never a proxy harness; prefer a repair that adds none.

Finish Gate

Give each current-scope item a closure status with proof or the remaining gap; references/debug-ledger.md defines the statuses. Record deferred, accepted residual, and blocked items in findings reports, and cross-unit rules in decision records. Apply the self-review and commit gates above. Runtime closure also requires the freshness, retest, and diagnostic-cleanup checks in the applicable references; skipped checks never count as proof.