# Agent Instruction Template -- Team Tech Debt Role-specific instruction templates for CSV wave agents in the tech debt pipeline. Each role has a specialized instruction that is injected as the `instruction` parameter to `spawn_agents_on_csv`. ## Purpose | Phase | Usage | |-------|-------| | Phase 1 | Orchestrator selects role-specific instruction based on task role | | Phase 2 | Injected as `instruction` parameter to `spawn_agents_on_csv` | --- ## Scanner Instruction ```markdown ## TECH DEBT SCAN TASK ### MANDATORY FIRST STEPS 1. Read shared discoveries: /discoveries.ndjson (if exists) 2. Read project context: .workflow/project-tech.json (if exists) --- ## Your Task **Task ID**: {id} **Title**: {title} **Role**: scanner **Dimension Focus**: {debt_dimension} **Pipeline Mode**: {pipeline_mode} ### Task Description {description} ### Previous Context {prev_context} --- ## Execution Protocol 1. **Read discoveries**: Load /discoveries.ndjson 2. **Detect project type**: Check package.json, pyproject.toml, go.mod, etc. 3. **Scan 5 dimensions**: - **Code**: Complexity > 10, TODO/FIXME, deprecated APIs, dead code, duplicated logic - **Architecture**: Circular dependencies, god classes, layering violations, tight coupling - **Testing**: Missing tests, low coverage, test quality issues, no integration tests - **Dependency**: Outdated packages, known vulnerabilities, unused dependencies - **Documentation**: Missing JSDoc/docstrings, stale API docs, no README sections 4. **Use tools**: mcp__ace-tool__search_context for semantic search, Grep for pattern matching, Bash for static analysis tools 5. **Standardize each finding**: - id: TD-NNN (sequential) - dimension: code|architecture|testing|dependency|documentation - severity: critical|high|medium|low - file: path, line: number - description: issue description - suggestion: fix suggestion - estimated_effort: small|medium|large|unknown 6. **Share discoveries**: Append each finding to discovery board: ```bash echo '{"ts":"","worker":"{id}","type":"debt_item_found","data":{"id":"TD-NNN","dimension":"","severity":"","file":"","line":,"description":"","suggestion":"","estimated_effort":""}}' >> /discoveries.ndjson ``` 7. **Write artifact**: Save structured inventory to /scan/debt-inventory.json 8. **Report result** --- ## Output (report_agent_job_result) { "id": "{id}", "status": "completed" | "failed", "findings": "Scanned N dimensions. Found M debt items: X critical, Y high... (max 500 chars)", "debt_items_count": "", "artifacts_produced": "scan/debt-inventory.json", "error": "" } ``` --- ## Assessor Instruction ```markdown ## TECH DEBT ASSESSMENT TASK ### MANDATORY FIRST STEPS 1. Read shared discoveries: /discoveries.ndjson (if exists) 2. Read debt inventory: /scan/debt-inventory.json --- ## Your Task **Task ID**: {id} **Title**: {title} **Role**: assessor ### Task Description {description} ### Previous Context {prev_context} --- ## Execution Protocol 1. **Load debt inventory** from /scan/debt-inventory.json 2. **Score each item**: - **Impact Score** (1-5): critical=5, high=4, medium=3, low=1 - **Cost Score** (1-5): small=1, medium=3, large=5, unknown=3 3. **Classify into priority quadrants**: | Impact | Cost | Quadrant | |--------|------|----------| | >= 4 | <= 2 | quick-win | | >= 4 | >= 3 | strategic | | <= 3 | <= 2 | backlog | | <= 3 | >= 3 | defer | 4. **Sort** within each quadrant by impact_score descending 5. **Share discoveries**: Append assessment summary to discovery board 6. **Write artifact**: /assessment/priority-matrix.json 7. **Report result** --- ## Output (report_agent_job_result) { "id": "{id}", "status": "completed" | "failed", "findings": "Assessed M items. Quick-wins: X, Strategic: Y, Backlog: Z, Defer: W (max 500 chars)", "debt_items_count": "", "artifacts_produced": "assessment/priority-matrix.json", "error": "" } ``` --- ## Planner Instruction ```markdown ## TECH DEBT PLANNING TASK ### MANDATORY FIRST STEPS 1. Read shared discoveries: /discoveries.ndjson (if exists) 2. Read priority matrix: /assessment/priority-matrix.json --- ## Your Task **Task ID**: {id} **Title**: {title} **Role**: planner ### Task Description {description} ### Previous Context {prev_context} --- ## Execution Protocol 1. **Load priority matrix** from /assessment/priority-matrix.json 2. **Group items**: quickWins (quick-win), strategic, backlog, deferred 3. **Create 3-phase remediation plan**: - **Phase 1: Quick Wins** -- High impact, low cost, immediate execution - **Phase 2: Systematic** -- High impact, high cost, structured refactoring - **Phase 3: Prevention** -- Long-term prevention mechanisms 4. **Map action types** per dimension: | Dimension | Action Type | |-----------|-------------| | code | refactor | | architecture | restructure | | testing | add-tests | | dependency | update-deps | | documentation | add-docs | 5. **Generate prevention actions** for dimensions with >= 3 items: | Dimension | Prevention | |-----------|------------| | code | Add linting rules for complexity thresholds | | architecture | Introduce module boundary checks in CI | | testing | Set minimum coverage thresholds | | dependency | Configure automated update bot | | documentation | Add docstring enforcement in linting | 6. **Write artifacts**: - /plan/remediation-plan.md (human-readable with checklists) - /plan/remediation-plan.json (machine-readable) 7. **Report result** --- ## Output (report_agent_job_result) { "id": "{id}", "status": "completed" | "failed", "findings": "Created 3-phase plan. Phase 1: X quick-wins. Phase 2: Y systematic. Phase 3: Z prevention. Total actions: N (max 500 chars)", "debt_items_count": "", "artifacts_produced": "plan/remediation-plan.md;plan/remediation-plan.json", "error": "" } ``` --- ## Executor Instruction ```markdown ## TECH DEBT FIX EXECUTION TASK ### MANDATORY FIRST STEPS 1. Read shared discoveries: /discoveries.ndjson (if exists) 2. Read remediation plan: /plan/remediation-plan.json --- ## Your Task **Task ID**: {id} **Title**: {title} **Role**: executor ### Task Description {description} ### Previous Context {prev_context} --- ## Execution Protocol **CRITICAL**: ALL file operations must execute within the worktree path. 1. **Load remediation plan** from /plan/remediation-plan.json 2. **Extract worktree path** from task description 3. **Group actions by type**: refactor -> update-deps -> add-tests -> add-docs -> restructure 4. **For each batch**: - Read target files in worktree - Apply changes following project conventions - Validate changes compile/lint: `cd "" && npx tsc --noEmit` or equivalent - Track: items_fixed, items_failed, files_modified 5. **After each batch**: Verify via `cd "" && git diff --name-only` 6. **Share discoveries**: Append fix_applied entries to discovery board: ```bash echo '{"ts":"","worker":"{id}","type":"fix_applied","data":{"file":"","change":"","lines_modified":,"debt_id":""}}' >> /discoveries.ndjson ``` 7. **Self-validate**: | Check | Command | Pass Criteria | |-------|---------|---------------| | Syntax | `cd "" && npx tsc --noEmit` | No new errors | | Lint | `cd "" && npx eslint --no-error-on-unmatched-pattern` | No new errors | 8. **Write artifact**: /fixes/fix-log.json 9. **Report result** --- ## Output (report_agent_job_result) { "id": "{id}", "status": "completed" | "failed", "findings": "Fixed X/Y items. Batches: refactor(N), update-deps(N), add-tests(N). Files modified: Z (max 500 chars)", "debt_items_count": "", "artifacts_produced": "fixes/fix-log.json", "error": "" } ``` --- ## Validator Instruction ```markdown ## TECH DEBT VALIDATION TASK ### MANDATORY FIRST STEPS 1. Read shared discoveries: /discoveries.ndjson (if exists) 2. Read fix log: /fixes/fix-log.json (if exists) --- ## Your Task **Task ID**: {id} **Title**: {title} **Role**: validator ### Task Description {description} ### Previous Context {prev_context} --- ## Execution Protocol **CRITICAL**: ALL validation commands must execute within the worktree path. 1. **Extract worktree path** from task description 2. **Load fix results** from /fixes/fix-log.json 3. **Run 4-layer validation**: **Layer 1 -- Test Suite**: - Command: `cd "" && npm test` or `cd "" && python -m pytest` - PASS: No FAIL/error/failed keywords - SKIP: No test runner available **Layer 2 -- Type Check**: - Command: `cd "" && npx tsc --noEmit` - Count: `error TS` occurrences **Layer 3 -- Lint Check**: - Command: `cd "" && npx eslint --no-error-on-unmatched-pattern ` - Count: error occurrences **Layer 4 -- Quality Analysis** (when > 5 modified files): - Compare code quality before/after - Assess complexity, duplication, naming improvements 4. **Calculate debt score**: - debt_score_after = debt items NOT in modified files (remaining unfixed) - improvement_percentage = ((before - after) / before) * 100 5. **Auto-fix attempt** (when total_regressions <= 3): - Fix minor regressions inline - Re-run validation checks 6. **Share discoveries**: Append regression_found entries if any: ```bash echo '{"ts":"","worker":"{id}","type":"regression_found","data":{"file":"","test":"","description":"","severity":""}}' >> /discoveries.ndjson ``` 7. **Write artifact**: /validation/validation-report.json with: - validation_date, passed (bool), total_regressions - checks: {tests, types, lint, quality} with per-check status - debt_score_before, debt_score_after, improvement_percentage 8. **Report result** --- ## Output (report_agent_job_result) { "id": "{id}", "status": "completed" | "failed", "findings": "Validation: PASSED|FAILED. Tests: OK/N failures. Types: OK/N errors. Lint: OK/N errors. Debt reduction: X% (max 500 chars)", "debt_items_count": "", "artifacts_produced": "validation/validation-report.json", "error": "" } ``` --- ## Placeholder Reference | Placeholder | Resolved By | When | |-------------|------------|------| | `` | Skill designer (Phase 1) | Literal path baked into instruction | | `{id}` | spawn_agents_on_csv | Runtime from CSV row | | `{title}` | spawn_agents_on_csv | Runtime from CSV row | | `{description}` | spawn_agents_on_csv | Runtime from CSV row | | `{role}` | spawn_agents_on_csv | Runtime from CSV row | | `{debt_dimension}` | spawn_agents_on_csv | Runtime from CSV row | | `{pipeline_mode}` | spawn_agents_on_csv | Runtime from CSV row | | `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row | --- ## Instruction Selection Logic The orchestrator selects the appropriate instruction section based on the task's `role` column: | Role | Instruction Section | |------|-------------------| | scanner | Scanner Instruction | | assessor | Assessor Instruction | | planner | Planner Instruction | | executor | Executor Instruction | | validator | Validator Instruction | Since each wave typically contains tasks from a single role (linear pipeline), the orchestrator uses the role of the first task in the wave to select the instruction template. The `` placeholder is replaced with the actual session path before injection.