Resolve Debt Phase

Contract

Role: public lifecycle entrypoint for one tech debt phase item
Scope: one candidate or accepted debt item, never generic debt management
Canonical input: <wiki-root>/content/docs/project/tech-debt/<domain>/<spec>/<debt-slug>.md, where <wiki-root> is the wiki location declared in the project wiki contract (apps/wiki by default)
Source of truth: debt file; backlog mirrors are secondary and may be stale
Delegates to: $parallel-research for independent readonly checks
Manual handoffs: accepted debt presents a bounded brief for explicit user invocation of $requirements-phase, then of $delivery-phase
Stop conditions: draft decision requested, accepted item waiting for explicit user $requirements-phase or $delivery-phase invocation, resolved item no-oped, or completed item marked resolved with links

The user provides or points to one tech debt artifact under <wiki-root>/content/docs/project/tech-debt/.
The user asks to validate, accept, delete, or resolve one debt candidate.
The user asks to continue an accepted tech debt item into implementation.

Creating a broad debt register, backlog cleanup, or multi-item debt campaign.
Resolving normal feature work with no canonical debt file.
The backlog issue is the only artifact and no debt file can be found or created by the owning workflow.

Locate the debt file at <wiki-root>/content/docs/project/tech-debt/<domain>/<spec>/<debt-slug>.md; stop if multiple items are implied.
Read the debt file first and extract status, domain, originating spec, linked backlog mirror, evidence, and proposed resolution.
Treat the debt file as canonical. Use backlog mirrors only to sync status or discover context.
Branch by status: draft, accepted, or resolved. If missing or ambiguous, inspect context and ask before changing state.

Run readonly validation before asking for a lifecycle decision.

Inspect the debt file.
Inspect original SPEC.md, PLAN.md, IMPLEMENTATION-NOTES.md, review notes, and related docs.
Inspect current code, tests, runtime logs, docs, and external evidence needed to prove whether the debt is real, stale, already fixed, or underspecified.
Use $parallel-research when checks can run independently across code, docs, tests, runtime evidence, or external sources.
Synthesize evidence with citations to local files, commands, logs, or sources.
Ask the user to choose exactly one: accept, delete, or authorize more research.

Start the requirements handoff only after the user accepts the draft item.

Move the one accepted item toward delivery through two explicit user handoffs.

Without a current Requirements result for this debt, build a requirements brief tied to the original domain/spec and debt slug. It states the initial debt, why it matters, the bounded fix, non-goals, acceptance checks, and closeout requirements.
Tell the user to invoke $requirements-phase explicitly with that brief, then stop without loading or running it. Requirements Phase compiles the debt-resolution ARCHITECTURE.md and SPEC.md pair and projects its backlog.
With that Requirements result, build and present a delivery brief naming the resolution spec, backlog identities, bounded fix, acceptance checks, closeout requirements, and implementation scope.
Tell the user to invoke $delivery-phase explicitly with that brief, then stop without loading or running it.

No-op by default.

When delivery finishes:

Update the debt file status to resolved.
Link the resolution spec.
Link implementation notes or final delivery evidence.
Record validation commands and outcomes.
Sync the backlog mirror when available, without treating it as source of truth.
Report any residual follow-up as new debt only if it is distinct from the resolved item.

Always report:

debt file path and status before/after
evidence inspected or validation performed
decision requested for draft, manual $requirements-phase or $delivery-phase handoff or returned delivery result for accepted, or no-op reason for resolved
resolution spec and implementation notes links when present
backlog mirror sync outcome when available