# Team Tech Debt

> Systematic tech debt governance with CSV wave pipeline. Scans codebase for tech debt across 5 dimensions, assesses severity with priority matrix, plans phased remediation, executes fixes in worktree, validates with 4-layer checks. Supports scan/remediate/targeted pipeline modes with fix-verify GC loop.

- Skill: `majiayu000/team-tech-debt` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/team-tech-debt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/team-tech-debt/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/team-tech-debt

---


## Auto Mode

When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.

# Team Tech Debt

## Usage

```bash
$team-tech-debt "Scan and fix tech debt in src/ module"
$team-tech-debt --mode=scan "Audit codebase for tech debt"
$team-tech-debt --mode=targeted "Fix known TODO/FIXME items in auth module"
$team-tech-debt -c 4 -y "Full remediation pipeline for entire project"
$team-tech-debt --continue "td-auth-debt-20260308"
```

**Flags**:
- `-y, --yes`: Skip all confirmations (auto mode)
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
- `--continue`: Resume existing session
- `--mode=scan`: Scan and assess only, no fixes
- `--mode=targeted`: Skip scan/assess, direct fix path for known debt
- `--mode=remediate`: Full pipeline (default)

**Output Directory**: `.workflow/.csv-wave/{session-id}/`
**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)

---

## Overview

Systematic tech debt governance: scan -> assess -> plan -> fix -> validate. Five specialized worker roles execute as CSV wave agents, with interactive agents for plan approval checkpoints and fix-verify GC loops.

**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)

```
+-------------------------------------------------------------------+
|              TEAM TECH DEBT WORKFLOW                                |
+-------------------------------------------------------------------+
|                                                                     |
|  Phase 0: Pre-Wave Interactive (Requirement Clarification)          |
|     +- Parse mode (scan/remediate/targeted)                         |
|     +- Clarify scope and focus areas                                |
|     +- Output: pipeline mode + scope for decomposition              |
|                                                                     |
|  Phase 1: Requirement -> CSV + Classification                       |
|     +- Select pipeline mode (scan/remediate/targeted)               |
|     +- Build task chain with fixed role assignments                 |
|     +- Classify tasks: csv-wave | interactive (exec_mode)           |
|     +- Compute dependency waves (linear chain)                      |
|     +- Generate tasks.csv with wave + exec_mode columns             |
|     +- User validates task breakdown (skip if -y)                   |
|                                                                     |
|  Phase 2: Wave Execution Engine (Extended)                          |
|     +- For each wave (1..N):                                        |
|     |   +- Execute pre-wave interactive tasks (plan approval)       |
|     |   +- Build wave CSV (filter csv-wave tasks for this wave)     |
|     |   +- Inject previous findings into prev_context column        |
|     |   +- spawn_agents_on_csv(wave CSV)                            |
|     |   +- Execute post-wave interactive tasks (if any)             |
|     |   +- Merge all results into master tasks.csv                  |
|     |   +- Check: any failed? -> skip dependents                    |
|     |   +- TDVAL checkpoint: GC loop check                          |
|     +- discoveries.ndjson shared across all modes (append-only)     |
|                                                                     |
|  Phase 3: Post-Wave Interactive (Completion + PR)                   |
|     +- PR creation (if worktree mode, validation passed)            |
|     +- Debt reduction metrics report                                |
|     +- Interactive completion choice                                |
|                                                                     |
|  Phase 4: Results Aggregation                                       |
|     +- Export final results.csv                                     |
|     +- Generate context.md with debt metrics                        |
|     +- Display summary: debt scores, reduction rate                 |
|     +- Offer: new target | deep fix | close                        |
|                                                                     |
+-------------------------------------------------------------------+
```

---

## Task Classification Rules

Each task is classified by `exec_mode`:

| exec_mode | Mechanism | Criteria |
|-----------|-----------|----------|
| `csv-wave` | `spawn_agents_on_csv` | One-shot scan, assessment, planning, execution, validation |
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Plan approval checkpoint, fix-verify GC loop management |

**Classification Decision**:

| Task Property | Classification |
|---------------|---------------|
| Multi-dimension debt scan (TDSCAN) | `csv-wave` |
| Quantitative assessment (TDEVAL) | `csv-wave` |
| Remediation planning (TDPLAN) | `csv-wave` |
| Plan approval gate | `interactive` |
| Debt cleanup execution (TDFIX) | `csv-wave` |
| Cleanup validation (TDVAL) | `csv-wave` |
| Fix-verify GC loop management | `interactive` |

---

## CSV Schema

### tasks.csv (Master State)

```csv
id,title,description,role,debt_dimension,pipeline_mode,deps,context_from,exec_mode,wave,status,findings,debt_items_count,artifacts_produced,error
"TDSCAN-001","Multi-dimension debt scan","Scan codebase across 5 dimensions for tech debt items","scanner","all","remediate","","","csv-wave","1","pending","","0","",""
"TDEVAL-001","Severity assessment","Quantify impact and fix cost for each debt item","assessor","all","remediate","TDSCAN-001","TDSCAN-001","csv-wave","2","pending","","0","",""
"TDPLAN-001","Remediation planning","Create phased remediation plan from priority matrix","planner","all","remediate","TDEVAL-001","TDEVAL-001","csv-wave","3","pending","","0","",""
```

**Columns**:

| Column | Phase | Description |
|--------|-------|-------------|
| `id` | Input | Unique task identifier (TDPREFIX-NNN) |
| `title` | Input | Short task title |
| `description` | Input | Detailed task description with scope and context |
| `role` | Input | Worker role: scanner, assessor, planner, executor, validator |
| `debt_dimension` | Input | `all`, `code`, `architecture`, `testing`, `dependency`, `documentation` |
| `pipeline_mode` | Input | `scan`, `remediate`, `targeted` |
| `deps` | Input | Semicolon-separated dependency task IDs |
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
| `exec_mode` | Input | `csv-wave` or `interactive` |
| `wave` | Computed | Wave number (1-based) |
| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
| `findings` | Output | Key discoveries or execution notes (max 500 chars) |
| `debt_items_count` | Output | Number of debt items found/fixed/validated |
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
| `error` | Output | Error message if failed |

### Per-Wave CSV (Temporary)

Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).

---

## Agent Registry (Interactive Agents)

| Agent | Role File | Pattern | Responsibility | Position |
|-------|-----------|---------|----------------|----------|
| Plan Approver | agents/plan-approver.md | 2.3 (send_input cycle) | Review remediation plan, approve/revise/abort | pre-wave (before TDFIX) |
| GC Loop Manager | agents/gc-loop-manager.md | 2.3 (send_input cycle) | Manage fix-verify loop, create retry tasks | post-wave (after TDVAL) |

> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.

---

## Output Artifacts

| File | Purpose | Lifecycle |
|------|---------|-----------|
| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
| `results.csv` | Final export of all task results | Created in Phase 4 |
| `discoveries.ndjson` | Shared exploration board (all agents) | Append-only, carries across waves |
| `context.md` | Human-readable report with debt metrics | Created in Phase 4 |
| `scan/debt-inventory.json` | Scanner output: structured debt inventory | Created by TDSCAN |
| `assessment/priority-matrix.json` | Assessor output: prioritized debt items | Created by TDEVAL |
| `plan/remediation-plan.md` | Planner output: phased fix plan | Created by TDPLAN |
| `plan/remediation-plan.json` | Planner output: machine-readable plan | Created by TDPLAN |
| `fixes/fix-log.json` | Executor output: fix results | Created by TDFIX |
| `validation/validation-report.json` | Validator output: validation results | Created by TDVAL |
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |

---

## Session Structure

```
.workflow/.csv-wave/{session-id}/
+-- tasks.csv                  # Master state
+-- results.csv                # Final results
+-- discoveries.ndjson         # Shared discovery board
+-- context.md                 # Human-readable report
+-- wave-{N}.csv               # Temporary per-wave input
+-- scan/
|   +-- debt-inventory.json    # Scanner output
+-- assessment/
|   +-- priority-matrix.json   # Assessor output
+-- plan/
|   +-- remediation-plan.md    # Planner output (human)
|   +-- remediation-plan.json  # Planner output (machine)
+-- fixes/
|   +-- fix-log.json           # Executor output
+-- validation/
|   +-- validation-report.json # Validator output
+-- interactive/
|   +-- {id}-result.json       # Interactive task results
+-- wisdom/
    +-- learnings.md
    +-- decisions.md
```

---

## Implementation

### Session Initialization

```javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3

// Detect pipeline mode
let pipelineMode = 'remediate'
if ($ARGUMENTS.includes('--mode=scan')) pipelineMode = 'scan'
else if ($ARGUMENTS.includes('--mode=targeted')) pipelineMode = 'targeted'

const requirement = $ARGUMENTS
  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--mode=\w+/g, '')
  .trim()

const slug = requirement.toLowerCase()
  .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
  .substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
const sessionId = `td-${slug}-${dateStr}`
const sessionFolder = `.workflow/.csv-wave/${sessionId}`

Bash(`mkdir -p ${sessionFolder}/scan ${sessionFolder}/assessment ${sessionFolder}/plan ${sessionFolder}/fixes ${sessionFolder}/validation ${sessionFolder}/interactive ${sessionFolder}/wisdom`)

// Initialize discoveries.ndjson
Write(`${sessionFolder}/discoveries.ndjson`, '')
Write(`${sessionFolder}/wisdom/learnings.md`, '# Learnings\n')
Write(`${sessionFolder}/wisdom/decisions.md`, '# Decisions\n')
```

---

### Phase 0: Pre-Wave Interactive (Requirement Clarification)

**Objective**: Parse mode, clarify scope, prepare pipeline configuration.

**Workflow**:

1. **Detect mode from arguments** (--mode=scan/remediate/targeted) or from keywords:

| Keywords | Mode |
|----------|------|
| scan, audit, assess | scan |
| targeted, specific, fix known | targeted |
| Default | remediate |

2. **Clarify scope** (skip if AUTO_YES):
   ```javascript
   AskUserQuestion({
     questions: [{
       question: "Tech debt governance scope:",
       header: "Scope Selection",
       multiSelect: false,
       options: [
         { label: "Full project scan", description: "Scan entire codebase" },
         { label: "Specific module", description: "Target specific directory" },
         { label: "Custom scope", description: "Specify file patterns" }
       ]
     }]
   })
   ```

3. **Detect debt dimensions** from task description:

| Keywords | Dimension |
|----------|-----------|
| code quality, complexity, smell | code |
| architecture, coupling, structure | architecture |
| test, coverage, quality | testing |
| dependency, outdated, vulnerable | dependency |
| documentation, api doc, comments | documentation |
| Default | all |

4. **Output**: pipeline mode, scope, focus dimensions

**Success Criteria**:
- Pipeline mode determined
- Scope and dimensions clarified

---

### Phase 1: Requirement -> CSV + Classification

**Objective**: Build task chain based on pipeline mode, generate tasks.csv.

**Pipeline Definitions**:

| Mode | Task Chain |
|------|------------|
| scan | TDSCAN-001 -> TDEVAL-001 |
| remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> (plan-approval) -> TDFIX-001 -> TDVAL-001 |
| targeted | TDPLAN-001 -> (plan-approval) -> TDFIX-001 -> TDVAL-001 |

**Task Registry**:

| Task ID | Role | Prefix | exec_mode | Wave | Description |
|---------|------|--------|-----------|------|-------------|
| TDSCAN-001 | scanner | TDSCAN | csv-wave | 1 | Multi-dimension codebase scan |
| TDEVAL-001 | assessor | TDEVAL | csv-wave | 2 | Severity assessment with priority matrix |
| PLAN-APPROVE | - | - | interactive | 3 (pre-wave) | Plan approval checkpoint |
| TDPLAN-001 | planner | TDPLAN | csv-wave | 3 | Phased remediation plan |
| TDFIX-001 | executor | TDFIX | csv-wave | 4 | Worktree-based incremental fixes |
| TDVAL-001 | validator | TDVAL | csv-wave | 5 | 4-layer validation |

**Worktree Creation** (before TDFIX, remediate mode):
```bash
git worktree add .worktrees/td-<slug>-<date> -b tech-debt/td-<slug>-<date>
```

**Wave Computation**: Linear chain, waves assigned by position in pipeline.

**User Validation**: Display pipeline with mode and task chain (skip if AUTO_YES).

**Success Criteria**:
- tasks.csv created with correct pipeline chain
- No circular dependencies
- User approved (or AUTO_YES)

---

### Phase 2: Wave Execution Engine (Extended)

**Objective**: Execute tasks wave-by-wave with checkpoints and GC loop support.

```javascript
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
let tasks = parseCsv(masterCsv)
const maxWave = Math.max(...tasks.map(t => t.wave))
let gcRounds = 0
const MAX_GC_ROUNDS = 3

for (let wave = 1; wave <= maxWave; wave++) {
  const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
  const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
  const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')

  // Check dependencies
  for (const task of waveTasks) {
    const depIds = (task.deps || '').split(';').filter(Boolean)
    const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
    if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
      task.status = 'skipped'
      task.error = `Dependency failed`
    }
  }

  // Pre-wave interactive: Plan Approval Gate (after TDPLAN completes)
  if (interactiveTasks.some(t => t.id === 'PLAN-APPROVE' && t.status === 'pending')) {
    Read('agents/plan-approver.md')
    const planTask = interactiveTasks.find(t => t.id === 'PLAN-APPROVE')

    const agent = spawn_agent({
      message: `## PLAN REVIEW\n\n### MANDATORY FIRST STEPS\n1. Read: ${sessionFolder}/plan/remediation-plan.md\n2. Read: ${sessionFolder}/discoveries.ndjson\n\nReview the remediation plan and decide: Approve / Revise / Abort\n\nSession: ${sessionFolder}`
    })
    const result = wait({ ids: [agent], timeout_ms: 600000 })

    // Parse decision
    if (result includes "Abort") {
      // Skip remaining pipeline
      for (const t of tasks.filter(t => t.status === 'pending')) t.status = 'skipped'
    } else if (result includes "Revise") {
      // Create revision task, re-run planner
      // ... create TDPLAN-revised task
    }
    // Approve: continue normally

    close_agent({ id: agent })
    planTask.status = 'completed'

    // Create worktree for fix execution
    if (pipelineMode === 'remediate' || pipelineMode === 'targeted') {
      Bash(`git worktree add .worktrees/${sessionId} -b tech-debt/${sessionId}`)
    }
  }

  // Execute csv-wave tasks
  const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
  for (const task of pendingCsvTasks) {
    task.prev_context = buildPrevContext(task, tasks)
  }

  if (pendingCsvTasks.length > 0) {
    Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))

    // Select instruction based on role
    const role = pendingCsvTasks[0].role
    const instruction = Read(`instructions/agent-instruction.md`)
    // Customize instruction for role (scanner/assessor/planner/executor/validator)

    spawn_agents_on_csv({
      csv_path: `${sessionFolder}/wave-${wave}.csv`,
      id_column: "id",
      instruction: buildRoleInstruction(role, sessionFolder, wave),
      max_concurrency: maxConcurrency,
      max_runtime_seconds: 900,
      output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
      output_schema: {
        type: "object",
        properties: {
          id: { type: "string" },
          status: { type: "string", enum: ["completed", "failed"] },
          findings: { type: "string" },
          debt_items_count: { type: "string" },
          artifacts_produced: { type: "string" },
          error: { type: "string" }
        }
      }
    })

    // Merge results
    const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
    for (const r of results) {
      const t = tasks.find(t => t.id === r.id)
      if (t) Object.assign(t, r)
    }
  }

  // Post-wave: TDVAL GC Loop Check
  const completedVal = tasks.find(t => t.id.startsWith('TDVAL') && t.status === 'completed' && t.wave === wave)
  if (completedVal) {
    // Read validation results
    const valReport = JSON.parse(Read(`${sessionFolder}/validation/validation-report.json`))

    if (!valReport.passed && gcRounds < MAX_GC_ROUNDS) {
      gcRounds++
      // Create fix-verify retry tasks
      const fixId = `TDFIX-fix-${gcRounds}`
      const valId = `TDVAL-recheck-${gcRounds}`
      tasks.push({
        id: fixId, title: `Fix regressions (GC #${gcRounds})`, role: 'executor',
        description: `Fix regressions found in validation round ${gcRounds}`,
        debt_dimension: 'all', pipeline_mode: pipelineMode,
        deps: completedVal.id, context_from: completedVal.id,
        exec_mode: 'csv-wave', wave: wave + 1, status: 'pending',
        findings: '', debt_items_count: '0', artifacts_produced: '', error: ''
      })
      tasks.push({
        id: valId, title: `Revalidate (GC #${gcRounds})`, role: 'validator',
        description: `Revalidate after fix round ${gcRounds}`,
        debt_dimension: 'all', pipeline_mode: pipelineMode,
        deps: fixId, context_from: fixId,
        exec_mode: 'csv-wave', wave: wave + 2, status: 'pending',
        findings: '', debt_items_count: '0', artifacts_produced: '', error: ''
      })
      // Extend maxWave
    } else if (!valReport.passed && gcRounds >= MAX_GC_ROUNDS) {
      // Accept current state
      console.log(`Max GC rounds (${MAX_GC_ROUNDS}) reached. Accepting current state.`)
    }
  }

  // Update master CSV
  Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
  Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
}
```

**Success Criteria**:
- All waves executed in order
- Plan approval checkpoint enforced before fix execution
- GC loop properly bounded (max 3 rounds)
- Worktree created for fix execution
- discoveries.ndjson accumulated across all waves

---

### Phase 3: Post-Wave Interactive (Completion + PR)

**Objective**: Create PR from worktree if validation passed, generate debt reduction report.

```javascript
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
const allCompleted = tasks.every(t => t.status === 'completed' || t.status === 'skipped')

// PR Creation (if worktree exists and validation passed)
const worktreePath = `.worktrees/${sessionId}`
const valReport = JSON.parse(Read(`${sessionFolder}/validation/validation-report.json`) || '{}')
if (valReport.passed && fileExists(worktreePath)) {
  Bash(`cd ${worktreePath} && git add -A && git commit -m "tech-debt: remediate debt items (${sessionId})" && git push -u origin tech-debt/${sessionId}`)
  Bash(`gh pr create --title "Tech Debt Remediation: ${sessionId}" --body "Automated tech debt cleanup. See ${sessionFolder}/context.md for details."`)
  Bash(`git worktree remove ${worktreePath}`)
}

// Debt reduction metrics
const scanReport = JSON.parse(Read(`${sessionFolder}/scan/debt-inventory.json`) || '{}')
const debtBefore = scanReport.total_items || 0
const debtAfter = valReport.debt_score_after || 0
const reductionRate = debtBefore > 0 ? Math.round(((debtBefore - debtAfter) / debtBefore) * 100) : 0

console.log(`
============================================
TECH DEBT GOVERNANCE COMPLETE

Mode: ${pipelineMode}
Debt Items Found: ${debtBefore}
Debt Items Fixed: ${debtBefore - debtAfter}
Reduction Rate: ${reductionRate}%
GC Rounds: ${gcRounds}/${MAX_GC_ROUNDS}
Validation: ${valReport.passed ? 'PASSED' : 'FAILED'}

Session: ${sessionFolder}
============================================
`)

// Completion action
if (!AUTO_YES) {
  AskUserQuestion({
    questions: [{
      question: "What next?",
      header: "Completion",
      multiSelect: false,
      options: [
        { label: "New target", description: "Run another scan/fix cycle" },
        { label: "Deep fix", description: "Continue fixing remaining items" },
        { label: "Close", description: "Archive session" }
      ]
    }]
  })
}
```

**Success Criteria**:
- PR created if applicable
- Debt metrics calculated and reported
- User informed of next steps

---

### Phase 4: Results Aggregation

**Objective**: Generate final results and human-readable report.

```javascript
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)

let contextMd = `# Tech Debt Governance Report\n\n`
contextMd += `**Session**: ${sessionId}\n`
contextMd += `**Mode**: ${pipelineMode}\n`
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`

contextMd += `## Debt Metrics\n`
contextMd += `| Metric | Value |\n|--------|-------|\n`
contextMd += `| Items Found | ${debtBefore} |\n`
contextMd += `| Items Fixed | ${debtBefore - debtAfter} |\n`
contextMd += `| Reduction Rate | ${reductionRate}% |\n`
contextMd += `| GC Rounds | ${gcRounds} |\n`
contextMd += `| Validation | ${valReport.passed ? 'PASSED' : 'FAILED'} |\n\n`

contextMd += `## Pipeline Execution\n\n`
for (const t of tasks) {
  const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
  contextMd += `${icon} **${t.title}** [${t.role}] ${t.findings || ''}\n\n`
}

Write(`${sessionFolder}/context.md`, contextMd)
```

**Success Criteria**:
- results.csv exported
- context.md generated with debt metrics
- Summary displayed to user

---

## Shared Discovery Board Protocol

**Format**: NDJSON (one JSON per line)

**Discovery Types**:

| Type | Dedup Key | Data Schema | Description |
|------|-----------|-------------|-------------|
| `debt_item_found` | `data.file+data.line` | `{id, dimension, severity, file, line, description, suggestion}` | Tech debt item identified |
| `pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Code pattern (anti-pattern) found |
| `fix_applied` | `data.file+data.change` | `{file, change, lines_modified, debt_id}` | Fix applied to debt item |
| `regression_found` | `data.file+data.test` | `{file, test, description, severity}` | Regression found during validation |
| `dependency_issue` | `data.package+data.issue` | `{package, current, latest, issue, severity}` | Dependency problem |
| `metric_recorded` | `data.metric` | `{metric, value, dimension, file}` | Quality metric recorded |

```jsonl
{"ts":"2026-03-08T10:00:00Z","worker":"TDSCAN-001","type":"debt_item_found","data":{"id":"TD-001","dimension":"code","severity":"high","file":"src/auth/jwt.ts","line":42,"description":"Complexity > 15","suggestion":"Extract helper functions"}}
{"ts":"2026-03-08T10:15:00Z","worker":"TDFIX-001","type":"fix_applied","data":{"file":"src/auth/jwt.ts","change":"Extracted 3 helper functions","lines_modified":25,"debt_id":"TD-001"}}
```

---

## Checkpoints

| Checkpoint | Trigger | Condition | Action |
|------------|---------|-----------|--------|
| Plan Approval Gate | TDPLAN-001 completes | Always (remediate/targeted mode) | Interactive: Approve / Revise / Abort |
| Worktree Creation | Plan approved | Before TDFIX | `git worktree add .worktrees/{session-id}` |
| Fix-Verify GC Loop | TDVAL-* completes | Regressions found | Create TDFIX-fix-N + TDVAL-recheck-N (max 3 rounds) |

---

## Pipeline Mode Details

### Scan Mode
```
Wave 1: TDSCAN-001 (scanner) -> Scan 5 dimensions
Wave 2: TDEVAL-001 (assessor) -> Priority matrix
```

### Remediate Mode (Full Pipeline)
```
Wave 1: TDSCAN-001 (scanner) -> Scan 5 dimensions
Wave 2: TDEVAL-001 (assessor) -> Priority matrix
Wave 3: TDPLAN-001 (planner) -> Remediation plan
         PLAN-APPROVE (interactive) -> User approval
Wave 4: TDFIX-001 (executor) -> Apply fixes in worktree
Wave 5: TDVAL-001 (validator) -> 4-layer validation
         [GC Loop: TDFIX-fix-N -> TDVAL-recheck-N, max 3]
```

### Targeted Mode
```
Wave 1: TDPLAN-001 (planner) -> Targeted fix plan
         PLAN-APPROVE (interactive) -> User approval
Wave 2: TDFIX-001 (executor) -> Apply fixes in worktree
Wave 3: TDVAL-001 (validator) -> 4-layer validation
         [GC Loop: TDFIX-fix-N -> TDVAL-recheck-N, max 3]
```

---

## Error Handling

| Error | Resolution |
|-------|------------|
| Circular dependency | Detect in wave computation, abort with error message |
| CSV agent timeout | Mark as failed in results, continue with wave |
| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
| Scanner finds no debt | Report clean codebase, skip to summary |
| Plan rejected by user | Abort pipeline or create revision task |
| Fix-verify loop stuck (>3 rounds) | Accept current state, continue to completion |
| Worktree creation fails | Fall back to direct changes with user confirmation |
| Validation tools not available | Skip unavailable checks, report partial validation |
| CSV parse error | Validate CSV format before execution, show line number |
| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
| Continue mode: no session found | List available sessions, prompt user to select |

---

## Core Rules

1. **Start Immediately**: First action is session initialization, then Phase 0/1
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
4. **CSV First**: Default to csv-wave for tasks; only use interactive for approval checkpoints
5. **Context Propagation**: prev_context built from master CSV, not from memory
6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
7. **Skip on Failure**: If a dependency failed, skip the dependent task
8. **GC Loop Bounded**: Maximum 3 fix-verify rounds before accepting current state
9. **Worktree Isolation**: All fix execution happens in git worktree, not main branch
10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped


---

## Coordinator Role Constraints (Main Agent)

**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.

15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
    - Spawns agents with task assignments
    - Waits for agent callbacks
    - Merges results and coordinates workflow
    - Manages workflow transitions between phases

16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
    - Wait patiently for `wait()` calls to complete
    - NOT skip workflow steps due to perceived delays
    - NOT assume agents have failed just because they're taking time
    - Trust the timeout mechanisms defined in the skill

17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
    - Use `send_input()` to ask questions or provide clarification
    - NOT skip the agent or move to next phase prematurely
    - Give agents opportunity to respond before escalating
    - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`

18. **No Workflow Shortcuts**: The coordinator MUST NOT:
    - Skip phases or stages defined in the workflow
    - Bypass required approval or review steps
    - Execute dependent tasks before prerequisites complete
    - Assume task completion without explicit agent callback
    - Make up or fabricate agent results

19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
    - Total execution time may range from 30-90 minutes or longer
    - Each phase may take 10-30 minutes depending on complexity
    - The coordinator must remain active and attentive throughout the entire process
    - Do not terminate or skip steps due to time concerns