---
name: task-forge
description: Use when creating implementation-ready beads tasks that need testing strategy, optimal implementation approach, and documentation requirements baked in — composes /create-task with parallel enrichment agents that analyze the codebase and produce concrete test specifications, algorithm/data-structure guidance, and doc quality standards so implementing agents don't need to re-research
user-invocable: true
---

# Task Forge

Multi-agent pipeline: create a beads task, then enrich it with concrete testing,
implementation, and documentation guidance so the implementing agent knows exactly
what to build.

**Core principle:** Invest enrichment effort at creation time to eliminate rework
at implementation time.

**Simplicity principle (MANDATORY):** Enrichment must reduce complexity, never
add it. Every enrichment recommendation is evaluated against the
`/reduce-complexity` framework: essential complexity stays, accidental is
removed. If Agent B (Implementation) recommends a new abstraction, helper, or
module, it must cite ≥2 concrete call sites that justify the shape — otherwise
inline the logic. `/reduce-complexity` is dispatched whenever the task
introduces new abstractions, touches a file that already exceeds complexity
thresholds, or is labeled "refactor" / "simplify".

## When to Use

- Creating any non-trivial beads task (features, bugs touching multiple files,
  coordination changes, performance-sensitive code)
- Enriching an existing task that lacks testing strategy or implementation depth
- When `/create-task` alone would produce a task needing significant follow-up research

**When NOT to use:**
- Trivial tasks (rename, typo, constant addition) — use `/create-task` directly
- When you only need validation — use `/review-task` instead

## Invocation

```
/task-forge "Fix off-by-one in window boundary check" --type=bug --priority=1
/task-forge --task=<existing-id>
/task-forge --dry-run "Refactor transform chain"
/task-forge --skip-enrichment "Add capacity hint" --type=task --priority=3
```

| Flag | Effect |
|------|--------|
| `--task=<id>` | Enrich an existing task instead of creating a new one |
| `--dry-run` | Print enriched task without creating/updating in beads |
| `--skip-enrichment` | Create via `/create-task` only, no enrichment |
| `--type`, `--priority`, `--labels`, `--files-hint`, `--parent`, `--quick` | Passed through to `/create-task` |

---

## Pipeline Overview

```
Phase 0  Create task (/create-task or load existing)
   |
Phase 1  Classify complexity + select domain skills (orchestrator, inline)
   |     Short-circuit: TRIVIAL -> output unchanged
   |
Phase 2  Parallel enrichment (3 agents + 0-2 domain skills)
   |     Agent A: Testing | Agent B: Implementation | Agent C: Documentation
   |     + domain skills dispatched based on signal scoring
   |
Phase 3  Synthesis (1 agent)
   |     Merge findings, resolve conflicts, filter by priority
   |
Gate     User approves / modifies / skips enrichments
   |
Phase 4  Integrate enrichments into task description
   |
Phase 5  Output summary
```

**Agent count:** 4-6 for standard/complex tasks. 0 for trivial.

---

## Phase 0 — Input & Task Creation

**New task** (default): Invoke `/create-task` with all provided arguments.
Capture the task ID and full description.

**Existing task** (`--task=<id>`): Run `bd show <id>`. If description < 5 lines,
warn and recommend `/create-task` first. Stop.

---

## Phase 1 — Classify & Select Skills

The orchestrator performs classification inline (no sub-agent).

### Signal Extraction

Extract from the task description:

| Signal | Source |
|--------|--------|
| `files_affected` | Count rows in "Files to Modify" table |
| `modules_crossed` | Count distinct crate directories in file paths |
| `touches_hot_path` | File path in engine/, coordination/ inner loops, stdx/ |
| `has_unsafe` | `unsafe` in code snippets or referenced files |
| `task_type` | Metadata: bug, task, feature, epic |
| `priority` | Metadata: 0-4 |
| `description_length` | Line count |

### Classification

```
TRIVIAL (all must hold):
  files_affected <= 1, modules_crossed <= 1,
  NOT touches_hot_path, NOT has_unsafe,
  task_type NOT IN (epic, feature), description_length >= 30
  -> Skip enrichment. Output task unchanged.

SIMPLE:
  files_affected <= 3, modules_crossed <= 1, priority >= 2
  -> Lightweight enrichment: Testing Agent + Doc Agent only.

COMPLEX (any triggers):
  files_affected >= 7, OR modules_crossed >= 3,
  OR task_type == epic,
  OR (priority <= 1 AND (touches_hot_path OR has_unsafe))
  -> Full enrichment + up to 3 domain skills.

STANDARD (default):
  Everything else.
  -> Full enrichment (3 agents) + up to 2 domain skills.
```

Present classification to user with override option (`enrich`, `skip`, `complex`).

### Domain Skill Selection — Signal Scoring

For STANDARD/COMPLEX tasks, select domain skills using weighted signals.
Dispatch when total weight >= threshold.

**Module-to-skill fast lookup (first filter):**

| Module/File | Domain skill candidates |
|-------------|----------------------|
| `src/app.rs` | `/performance-analyzer`, `/security-reviewer`, `/interface-design-review` |
| `src/cache.rs` | `/performance-analyzer`, `/security-reviewer`, `/bench-compare` |
| `src/s3_dynamo_cache_handlers.rs` | `/performance-analyzer`, `/security-reviewer` |
| `src/config.rs` | `/interface-design-review`, `/security-reviewer` |
| `src/utils.rs` | `/performance-analyzer`, `/security-reviewer` |
| `src/interceptors/` | `/performance-analyzer`, `/security-reviewer` |
| `src/metrics/` | `/performance-analyzer`, `/interface-design-review` |

**Signal tables (second filter):**

| Skill | Trigger signals (weight) | Threshold |
|-------|-------------------------|-----------|
| `/performance-analyzer` | HOT-tier path (5), keywords: allocation/hot path/latency (3), `.clone()` in loop (4) | 5 |
| `/bench-compare` | Crate has `benches/` with Criterion (5), function called from benchmark (4) | 5 |
| `/simd-optimize` | File imports `std::arch` (5), keywords: SIMD/vectorize/NEON/AVX (4) | 5 |
| `/asm-forge` | Keywords: codegen/assembly/inline(always) (4), `#[inline(always)]` in HOT-tier (3) | 4 |
| `/dist-sys-auditor` | Path in coordination/ (5), keywords: lease/epoch/fence/shard (4) | 4 |
| `/sim-review` | Path in sim/ (5), keywords: simulation/deterministic/DST (4) | 4 |
| `/unsafe-review` | File contains `unsafe` (5), keywords: raw pointer/MaybeUninit/transmute (4) | 4 |
| `/safe-over-unsafe` | New `pub` API wrapping unsafe (5). Only if `/unsafe-review` also triggers. | 5 |
| `/interface-design-review` | New pub fn/struct/trait (4), in media-cache-contracts/ (5) | 4 |
| `/security-reviewer` | Path in scanner-git/ (4), keywords: parse/buffer/input validation (3), manual `&[u8]` indexing (4) | 4 |
| `/reduce-complexity` | New abstraction/trait/module proposed (5), keywords: refactor/simplify/cleanup/extensible/flexible/configurable (4), file already >300 LOC or function >100 LOC in "Files to Modify" (3), task_type == refactor or label contains "complexity"/"tech-debt" (5) | 4 |

**Budget caps:**

| Level | Max domain skills | Notes |
|-------|------------------|-------|
| SIMPLE | 0 | — |
| STANDARD | 2 | Mutual exclusions: `/performance-analyzer` XOR `/rust-hotspot-finder`; `/causal-profile` XOR `/perf-topdown` |
| COMPLEX | 3 | Same exclusions; `/test-consolidate` XOR `/test-dedup` |

**Safety override:** `/unsafe-review` and `/security-reviewer` bypass budget caps
when signal weight >= 7.

### Implementation Skill Recommendation

After selecting enrichment skills (dispatched NOW), compute a separate set of
**recommended implementation skills** — skills the IMPLEMENTING agent should
invoke when it picks up the task. These are advisory, not dispatched.

**Distinction:** Enrichment skills analyze the task to produce recommendations.
Implementation skills help the agent execute the work correctly. Choosing the
right skills is the difference between decent and great output.

#### Taxonomy — Organized by Implementation Phase

Skills are grouped by WHEN the implementing agent should invoke them.
Within each phase, skills are ordered by domain and natural chain order.

##### Before Starting Implementation

Use these before writing code — they shape the approach.

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/plan-forge` | COMPLEX task, or multiple viable approaches, or ≥7 files affected | Stress-test the implementation plan before coding starts |
| `/deep-research` | Task involves novel algorithms, safety-critical protocols, or designs where getting it wrong is expensive | Evidence-backed design from papers and production systems |
| `/deeper-research` | `/deep-research` insufficient; topic needs adversarial challenge | 6-phase funnel with adversarial review for highest stakes |
| `/design-tournament` | COMPLEX task with ≥3 viable implementation approaches | Competing proposals evaluated by independent agents |

##### During Implementation

**Testing**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/test-strategy` | Task creates new test files or significantly changes coverage | Choose the right test type (unit/rstest/proptest/fuzz/kani/sim) |
| `/invariant-test-review` | Task adds/modifies state-machine, simulation, or oracle tests | Ensure tests actually prove the claimed invariant, not just pass |
| `/run-fuzz` | Task handles untrusted input, parsers, or data structure serialization | Crash discovery via cargo-fuzz before merging |

**Performance** (chain: find → analyze → benchmark → optimize)

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/rust-hotspot-finder` | Performance optimization without a specific target function | Scan for likely hotspots before profiling — focus effort |
| `/performance-analyzer` | Task modifies HOT-tier code | Static analysis catches allocation violations and hot-path issues early |
| `/bench-compare` | Task touches functions with existing Criterion benchmarks | Validate no >5% median regression against baseline |
| `/perf-regression` | Task modifies hot-path code in coordination or scanner engine | Full benchmark suite before/after regression test |
| `/asm-forge` | Task modifies tight loops or `#[inline(always)]` in HOT-tier | Instruction-level analysis: bounds checks, register spills, codegen |
| `/simd-optimize` | Task touches byte-processing loops or SIMD paths | Platform-specific intrinsics (x86 + ARM NEON/SVE) with validation |
| `/heap-profile` | Task changes allocation patterns in HOT/WARM tier | Attribute allocations to call sites when AllocGuard trips |
| `/perf-topdown` | Task needs CPU µarch analysis (branch mispredict, cache miss) | Classify slow code: front-end vs back-end vs speculation |
| `/causal-profile` | Task modifies concurrent/async code on critical path | Distinguish critical-path bottlenecks from parallel slack |
| `/linux-perf-profile` | Task needs hardware PMU counters beyond flamegraphs | Source-level drill-down on Linux/ARM/Graviton targets |
| `/perf-pipeline` | Multiple perf dimensions need simultaneous triage | Orchestrates diagnosis + optimization dispatch in one pass |
| `/pgo-bolt` | Final optimization pass on a binary target | 10-30% from I-cache, branch prediction, function layout |

**Safety & Security** (chain: review → wrap → audit)

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/unsafe-review` | Task adds or modifies unsafe blocks | Audit safety invariants; demand benchmark+ASM proof of perf benefit |
| `/safe-over-unsafe` | Task creates pub API wrapping unsafe internals | Design safe wrapper that's hard to misuse |
| `/security-reviewer` | Task handles untrusted input, parsing, or buffer manipulation | Memory safety and security audit |

**Coordination & Distributed Systems** (chain: audit → specify → simulate → test)

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/dist-sys-auditor` | Task modifies coordination protocols or distributed state | Audit against academic literature and battle-tested systems |
| `/tla-spec` | Task changes coordination protocol semantics (leases, epochs, fences) | Formally verify safety/liveness properties before coding |

**Design & Architecture**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/interface-design-review` | Task adds new pub trait/struct/fn to contracts crate | Misuse-resistant API design review |

**Domain-Specific**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/rule-optimize` | Task adds/modifies rules in `default_rules.yaml` | Benchmark rule perf against test corpuses; validate anchors |
| `/sqlite-review` | Task touches SQLite schemas, queries, or WAL config | EXPLAIN QUERY PLAN evidence for schema decisions |
| `/postgres-review` | Task touches PostgreSQL schemas or migrations | Lock safety, query performance, and index optimization |

##### After Implementation

**Documentation** (chain: write → verify → audit)

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/doc-rigor` | Always — run after implementation | Write-then-verify documentation pipeline |
| `/doc-rigor-verify` | Task changes pub API signatures, command examples, or platform-specific behavior | Independent accuracy verification with zero confirmation bias |
| `/doc-verify` | Task adds unsafe invariants or changes pub API contracts | Fresh-agent verification against code reality |
| `/doc-code-audit` | Task touches code in scope of a design doc (`project documentation`) | Verify design doc still matches code |
| `/design-doc-audit` | Task touches multiple files covered by design docs, or adds new source files | Comprehensive doc coverage and accuracy check |

**Testing Verification**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/test-pipeline` | Feature implementation complete; need coverage gap assessment | Two-phase assess-then-improve testing |
| `/test-dedup` | Task added many tests to modules with existing property/sim coverage | Remove redundant unit tests that duplicate higher-level coverage |
| `/test-consolidate` | Task touches test modules with >15 existing similar tests | Consolidate verbose suites into rstest/proptest/fuzz |

**Code Quality**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/simplify` | Always — run before closing task | Final code simplification pass |
| `/dedup-audit` | Task introduces new types/functions that cross ≥2 crates | Catch accidental duplication before it drifts |

**Review**

| Skill | Recommend When | Why |
|-------|---------------|-----|
| `/review-dispatch` | Task is COMPLEX or crosses ≥3 modules | Six parallel specialist agents for thorough review |
| `/review-pipeline` | COMPLEX task needing review + automated fixes in one pass | Diagnose-then-fix pipeline |
| `/execute-review-findings` | After `/review-dispatch` produces multiple findings | Systematically address findings across files and severities |

#### Skill Chains

When recommending multiple skills from the same domain, ORDER them as chains.
Earlier skills produce findings that inform later skills. The synthesizer
should present chains as ordered sequences, not unordered lists.

| Chain | Progression | Trigger |
|-------|-------------|---------|
| **Perf optimization** | `/rust-hotspot-finder` → `/performance-analyzer` → `/bench-compare` → `/asm-forge` → `/simd-optimize` | HOT-tier optimization task |
| **Perf diagnosis** | `/perf-regression` → `/perf-topdown` → `/causal-profile` → `/linux-perf-profile` | Benchmark regression needing root cause |
| **Coordination** | `/dist-sys-auditor` → `/tla-spec` → `/sim-run` → `/jepsen-test` | Protocol correctness task |
| **Safety** | `/unsafe-review` → `/safe-over-unsafe` → `/security-reviewer` | New or modified unsafe code |
| **Documentation** | `/doc-rigor` → `/doc-verify` → `/design-doc-audit` | Post-implementation doc pass |
| **Testing** | `/test-strategy` → `/invariant-test-review` → `/test-pipeline` → `/test-dedup` | Comprehensive test coverage |
| **Review** | `/review-dispatch` → `/execute-review-findings` → `/simplify` | Pre-merge quality pass |
| **Planning** | `/deep-research` → `/plan-forge` → `/design-tournament` | COMPLEX task kickoff |

**Chain rules:**
- Never recommend a later chain step without also recommending earlier steps.
- If only part of a chain applies, truncate — don't skip middle steps.
- Chains are advisory ordering; the agent may interleave with coding.

#### Selection Process

1. Apply the same signal extraction from the task description.
2. Score each implementation skill against the taxonomy triggers.
3. All matching skills are included — no budget cap (advisory only).
4. Assemble matching skills into chains where applicable. If a skill
   appears in a chain, include preceding chain steps that also match.
5. Each enrichment agent also contributes 0-3 domain-specific picks (Phase 2).
6. The synthesizer (Phase 3) merges, deduplicates, orders by chain,
   and adds concrete invocation context.

#### Invocation Guidance Format

Each recommended skill gets a **when** (at what point during implementation)
and a **why** (what it catches or validates):

```
| Phase | Skill | When to Invoke | Why |
|-------|-------|---------------|-----|
| During | `/bench-compare` | After implementing the optimization | Validate no >5% regression |
| After | `/invariant-test-review` | After writing sim tests | Ensure tests prove claimed invariant |
| After | `/doc-rigor` | After all code is written | Write-then-verify documentation |
```

The orchestrator passes the initial skill set + chain analysis to the synthesizer.

---

## Phase 2 — Parallel Enrichment

Launch **all enrichment agents + domain skills in a single message** using the
Agent tool. Each agent gets the full task description, scope assessment, and
project policies.

### Common Preamble (included in all three agent prompts)

```
You are a task enrichment specialist. Your ONE job: enrich the task below
through the lens of {SPECIALTY}. Do NOT implement the task. Do NOT modify
files. Explore the codebase (Read, Grep, Glob) to ground recommendations.

This project has `colgrep` installed - a semantic code search tool.
Use `colgrep` (via Bash) as your PRIMARY search tool instead of Grep/Glob.
- Semantic search: `colgrep "error handling" -k 10`
- Regex + semantic: `colgrep -e "fn.*test" "unit tests"`

## Task Under Enrichment

{FULL_TASK_DESCRIPTION}

## Scope Assessment

- Complexity: {TRIVIAL|SIMPLE|STANDARD|COMPLEX}
- Files affected: {N} | Modules crossed: {N}
- Touches HOT path: {yes|no} | Has unsafe: {yes|no}
- Task type: {type} | Priority: P{N}

## Project Policies (MUST respect)

- **Allocation tiers**: HOT (per-shard/per-claim loops — allocation-silent),
  WARM (frequent ops — simplicity first), COLD (startup — no constraints)
- **No versioning**: No V1/V2, no deprecated, no compatibility shims
- **Error types**: thiserror + existing macros (impl_from_coord_error!, etc.)
- **Comment policy**: No tracking IDs, PR refs, temporal narration
- **Duplication prevention**: Search before creating anything new

## Output Rules

- Be concrete: cite file paths, function names, code patterns from the codebase.
- Rate each recommendation: MUST | SHOULD | COULD, with confidence 0-100%.
- Discard anything below 50% confidence.
- Maximum 10 recommendations. Focus on highest value.
```

### Agent A — Testing Enrichment

**Specialty: TESTING STRATEGY**

Agent A embeds the `/test-strategy` decision framework directly:

```
## Testing Toolkit

| Type | Tool | Best For |
|------|------|----------|
| Unit | #[test] | Specific behavior, edge cases, regression |
| Parameterized | rstest | Finite (input, expected) pairs, enum mappings |
| Property | proptest | Invariants over input domains, roundtrips |
| Fuzz | cargo-fuzz | Untrusted input, parsers, security-critical |
| Model Check | Kani | Memory safety proofs, absence of panics in unsafe |
| Simulation | Integration tests | Coordination protocol invariants S1-S9, fault tolerance |
| Simulation | Unit tests | Scanner engine detection pipeline |
| Simulation | Integration tests | Scheduler work-stealing, chunking |

## Decision Framework

- Fixed known inputs -> unit test (#[test])
- Finite (input, expected) pairs -> rstest parameterized
- Large/infinite input space -> proptest
- Untrusted/adversarial input -> fuzz test
- Memory safety in unsafe -> Kani proof
- Cache behavior change -> Integration tests
- Proxy behavior change -> Integration tests
- Config change -> Unit tests

## Your Steps

1. **Audit existing coverage**: For each file in "Files to Modify", find
   #[cfg(test)] mod tests, sibling test files, proptest/rstest usage.
   Catalog what IS tested and what IS NOT tested.

2. **Apply decision framework**: For each untested or new behavior, decide
   the test type using the framework above.

3. **Check duplication risk**: For each recommended test, search existing
   tests that might already cover this behavior. Flag overlap.

4. **Specify concrete tests**: For each recommendation provide:
   - Test name (test_{behavior}_{condition})
   - Test type
   - File location (which mod tests block)
   - Inputs to test
   - Property or invariant being verified
   - 5-10 line Rust code sketch (real code, not pseudocode)
   - Dependencies needed (rstest.workspace = true, feature flags)

5. **Specify what NOT to test**: Behaviors already covered by existing
   proptest/sim tests. This prevents test duplication.

## Dependencies Reference

- rstest: workspace dep "0.25" — add rstest.workspace = true to [dev-dependencies]
- proptest: direct dev-dependency (no feature gate)
- Simulation: feature "test-support" or "scheduler-sim" or "tiger-harness"
- Kani: feature "kani", run with cargo kani
- Fuzz: targets in crates/<crate>/fuzz/fuzz_targets/

## Output Format

### Existing Coverage Audit
| File | Tests Found | Coverage Assessment |

### Recommended Tests
For each:
- **Name**: test_{behavior}_{condition}
- **Type**: {unit|rstest|proptest|fuzz|kani|sim}
- **Location**: {file}:{mod tests}
- **Property**: {what this proves}
- **Priority**: {MUST|SHOULD|COULD} | **Confidence**: {N}%
- **Duplication risk**: {none|low|high — reason}
- **Code sketch**:
(5-10 lines of concrete Rust test code)

### Do NOT Test (Already Covered)
| Behavior | Covered By | Location |

### Test Dependencies
| Dependency | Crate | How to Add |

### Recommended Skills for Implementing Agent
List 0-5 skills from your testing domain that the implementing agent should
invoke. Only recommend if directly relevant. Consider the full palette:
`/sim-run`, `/run-fuzz`, `/jepsen-test`, `/test-pipeline`, `/test-dedup`,
`/test-consolidate`. Order as a chain if multiple apply.
| Skill | When to Invoke | Why |
```

### Agent B — Implementation Enrichment

**Specialty: IMPLEMENTATION APPROACH OPTIMIZATION (simplicity-first)**

Agent B embeds the `/reduce-complexity` framework directly: every
recommendation must be evaluated against essential-vs-accidental complexity,
reuse-over-create, and the anti-abstraction brake.

```
## Your Steps

0. **Simplicity gate (RUN FIRST)**: Before evaluating performance or structure,
   ask: can this task be done with LESS code rather than more?
   - Can any existing function be called with different args instead of a new helper?
   - Can the change be expressed as a 1-line edit rather than a new module?
   - Is the task proposing a new abstraction? If yes, grep for current call
     sites that would use it. Require ≥2; otherwise recommend INLINE.
   - Apply /reduce-complexity thresholds to any new function sketch:
     • LOC projected > 100 → break up or delete scope
     • nesting > 4 → use guard clauses / let-else / early returns
     • params >= 6 → struct the args OR split the function's two concerns
   - Apply the over-abstraction brake:
     `param_count + return_type_fields >= body_lines / 3` → warn
     single call site + >3 params → warn

1. **Classify allocation tier**: For each file in "Files to Modify":
   - HOT: inside engine/core.rs, coordination acquire/complete/checkpoint
     loops, per-claim/per-shard/per-tick iteration, benchmarked functions
   - WARM: query/list/admin operations, not in inner loops
   - COLD: startup, registration, setup/teardown, test helpers
   - Check existing patterns in the file (ByteSlab, InlineVec, with_capacity)

2. **Evaluate proposed approach**: For the task's "Desired State":
   - Is it the simplest correct approach for the allocation tier?
   - Better algorithm? (linear scan vs binary search vs hash, given data size)
   - Better data structure? (Vec vs InlineVec for small collections,
     HashMap vs BTreeMap for ordered access)
   - Can src/utils.rs utilities be reused?
   - **Prefer reuse over create.** If an existing utility is 80% correct,
     extend it; don't clone it.

3. **Check reusable utilities**: Search src/utils.rs for:
   - ByteSlab/ByteSlot — byte pooling
   - InlineVec<T, N> — stack-first small collections
   - RingBuffer<T, N> — fixed-capacity circular queue
   - AcquireScratch/FixedBuf — reusable scratch buffers
   Search sibling modules for existing patterns.

4. **Identify performance constraints**:
   - HOT: allocation points to avoid, branchless opportunities,
     SIMD-amenable patterns, false sharing risks
   - WARM: unnecessary allocations, with_capacity opportunities
   - COLD: no constraints, optimize for clarity

5. **Find existing patterns**: Has this algorithm been implemented elsewhere?
   What error handling and return types do sibling functions use?

6. **Simplification opportunities**: For each file in "Files to Modify",
   list accidental complexity the implementing agent should eliminate as part
   of this change (dead branches, redundant checks, unused fields, unnecessary
   wrappers, duplicated logic with sibling modules). Flag as MUST if the task
   fix is blocked by it, SHOULD otherwise.

## Output Format

### Simplicity Analysis (apply /reduce-complexity framework)
| Proposed element | Current call sites | Verdict | Rationale |
|------------------|-------------------|---------|-----------|
(Verdict: KEEP, INLINE, REUSE-EXISTING, DELETE-SCOPE, PARAMETERIZE-LESS)

### Simplification Opportunities
| File:line/function | Accidental complexity | Fix | Priority |

### Allocation Tier Classification
| File | Tier | Evidence | Constraints |

### Algorithm & Data Structure Recommendations
For each:
- **Location**: {file:line or function}
- **Current approach**: {what task says or implies}
- **Recommended approach**: {better alternative}
- **Why**: {complexity, allocation, benchmark evidence}
- **Priority**: {MUST|SHOULD|COULD} | **Confidence**: {N}%
- **Code sketch**: (concrete Rust code if non-obvious)

### Reusable Utilities
| Utility | Location | How to Apply |

### Performance Constraints (for implementing agent)
- {constraint with rationale}

### Anti-Patterns to Avoid
| Anti-Pattern | Why | What to Do Instead |

### Recommended Skills for Implementing Agent
List 0-5 skills from your performance/implementation domain that the
implementing agent should invoke. Only recommend if directly relevant.
Consider the full palette:
`/performance-analyzer`, `/rust-hotspot-finder`, `/bench-compare`,
`/perf-regression`, `/asm-forge`, `/simd-optimize`, `/heap-profile`,
`/perf-topdown`, `/causal-profile`, `/linux-perf-profile`, `/perf-pipeline`,
`/pgo-bolt`, `/dedup-audit`, `/plan-forge`. Order as a chain if multiple apply.
| Skill | When to Invoke | Why |
```

### Agent C — Documentation Enrichment

**Specialty: DOCUMENTATION REQUIREMENTS**

```
## Your Steps

1. **Audit doc state**: For each file in "Files to Modify":
   - Module-level docs present? Accurate?
   - Type docs on pub structs/enums/traits?
   - Function docs on pub fn with params/returns/errors/panics?
   - # Safety sections on unsafe functions?
   - # Examples on public APIs with non-obvious usage?
   - Stale docs that no longer match current code?

2. **Determine requirements based on task changes**:
   - New pub types -> type-level docs (purpose, invariants)
   - New pub functions -> function docs (params, returns, errors, panics)
   - New unsafe -> # Safety section with invariants
   - New algorithms -> algorithm overview (complexity, design trade-offs)
   - Changed behavior -> update docs on affected items
   - New error variants -> doc on each variant (when it occurs)

3. **Specify quality standards per item**:
   - [ ] Problem statement and scope
   - [ ] Invariants and safety rules
   - [ ] Algorithm overview (if applicable)
   - [ ] Design trade-offs (if applicable)
   - [ ] Edge cases and failure modes
   - [ ] Complexity/performance constraints (if applicable)
   - [ ] Examples (if public API with non-obvious usage)

4. **Reference existing patterns**: Find well-documented sibling code.
   Cite as "document like {file:line}" with rationale.

## Project Comment Policy (MUST follow)

Comments must stand alone. No tracking IDs, milestone labels, PR references,
temporal narration ("previously", "was changed from"), or conversational tone.
A reader with no access to PR/issue tracker must understand the comment.

## Output Format

### Current Doc Coverage
| File | Module Docs | Type Docs | Function Docs | Gaps |

### Required Documentation
For each:
- **Item**: {type/function/module name}
- **File**: {path}
- **Scope**: {module|type|function|inline}
- **Must cover**: {checklist items that apply}
- **Pattern to follow**: {file:line of similar well-documented item}
- **Priority**: {MUST|SHOULD|COULD} | **Confidence**: {N}%

### Doc Quality Checklist (for implementing agent)
- [ ] {specific item relevant to this task}

### Stale Docs to Update
| File:Line | Current Doc | What Changed | Required Update |

### Recommended Skills for Implementing Agent
List 0-5 skills from your documentation/quality domain that the implementing
agent should invoke. Only recommend if directly relevant. Consider the full
palette: `/doc-rigor`, `/doc-rigor-verify`, `/doc-verify`, `/doc-code-audit`,
`/design-doc-audit`, `/simplify`, `/dedup-audit`, `/review-dispatch`,
`/review-pipeline`, `/execute-review-findings`.
Order as a chain if multiple apply.
| Skill | When to Invoke | Why |
```

### Domain Skill Dispatch

For each domain skill selected in Phase 1, dispatch as a parallel Agent using
the scoped prompt pattern from `/review-task` Phase 1.5:

```
You are being invoked as a domain enrichment step during task forge.
Your job is NOT a full audit. Produce a focused report answering:

- What domain-specific edge cases or gotchas does the task miss?
- What domain-specific patterns, utilities, or conventions should it reference?
- What domain-specific acceptance criteria should be added?
- What domain-specific risks should be called out?

Keep output concise — 5-15 specific, actionable items.

## Task Description
{FULL_TASK_DESCRIPTION}

## Your Domain
{SKILL_NAME}: {brief scope description}
```

If a domain skill fails or times out, proceed without it. Note the gap in
the synthesis.

---

## Phase 3 — Synthesis

After all Phase 2 agents complete, launch **one synthesizer agent**.

### Synthesizer Prompt

```
You are the Task Forge Synthesizer. Three enrichment agents have independently
analyzed a beads task. Your job: merge their outputs into coherent enrichment
sections ready to be integrated into the task description.

## Original Task
{FULL_TASK_DESCRIPTION}

## Enrichment Reports
### Testing Enrichment (Agent A)
{REPORT}

### Implementation Enrichment (Agent B)
{REPORT}

### Documentation Enrichment (Agent C)
{REPORT}

{DOMAIN_ENRICHMENT_REPORTS if any}

## Your Responsibilities

### 1. Resolve Conflicts

Check for contradictions between agents:
- Testing recommends proptest but Implementation says HOT path forbids
  generator allocations -> use Kani proof or inline unit test instead
- Implementation recommends InlineVec but Testing sketch uses Vec
  -> update sketch to match implementation
- Doc agent says add # Examples but Implementation says API is internal
  -> skip examples, add inline comments instead

**Conflict resolution precedence:**
1. Project policy always wins (allocation tiers, comment policy, no-versioning)
2. Correctness/safety always wins over performance/ergonomics
3. **Simplicity wins over ergonomic sugar.** When agents disagree on an
   abstraction, prefer the approach with fewer moving parts, fewer call sites,
   and less indirection — per the `/reduce-complexity` framework.
4. Implementation agent wins on HOT-path constraints
5. Testing agent wins on coverage decisions (what to test)
6. Documentation agent wins on doc scope (what to document)
7. Higher confidence wins when no domain precedence applies

**Cross-agent simplicity filter:** After resolving conflicts, sweep the final
recommendation set for unjustified complexity:
- Any recommendation that adds a new module/trait/abstraction with <2 current
  call sites → demote to a note, not a requirement.
- Any recommendation to "make it more generic" / "add a knob" without concrete
  need → drop.
- Prefer DELETE and REUSE recommendations over CREATE when semantically
  equivalent.

### 2. Deduplicate

Merge overlapping recommendations from multiple agents.

### 3. Filter

- Keep all MUST items.
- Keep SHOULD with confidence >= 60%.
- Discard COULD with confidence < 70%.

### 4. Produce Integrated Enrichment Sections

Structure output as sections ready for task insertion:

#### Testing Strategy
(Replaces any existing section. Include concrete test names, types,
code sketches, and what NOT to test.)

#### Implementation Guidance Addendum
(Appended to existing Implementation Guidance. Algorithm/data structure
recommendations, allocation constraints, reusable utilities, anti-patterns.
Do NOT duplicate what's already in the task.)

#### Documentation Requirements
(New section. What docs to write, quality standards, patterns to follow.)

#### Performance Considerations
(New or replacement section, if applicable. Merge implementation agent's
allocation tier analysis with domain skill performance findings.)

### 5. Produce Recommended Skills Section

Merge implementation skill recommendations from three sources:
1. **Orchestrator's taxonomy-based picks** (passed in with this prompt)
2. **Each enrichment agent's "Recommended Skills" output** (0-3 each)
3. **Your own judgment** from reviewing the enrichment findings

For each recommended skill, produce:
- **Skill name** (slash command)
- **When to invoke** (at what point during implementation)
- **Why** (what it catches, validates, or improves — grounded in enrichment findings)

**Ordering:** Skills the agent should invoke DURING implementation first
implementation (e.g., `/bench-compare`, `/doc-rigor`, `/review-dispatch`).

**Deduplication:** If multiple agents recommend the same skill, keep the
most specific "when" and "why". Merge, don't list twice.

**Minimum set:** Always include `/doc-rigor` (after implementation),
`/reduce-complexity` (after implementation, before closing — verify no new
HIGH/CRITICAL hotspots were introduced on modified files), and `/simplify`
(before closing). Omit only if task is TRIVIAL.

### 6. Rate Enrichment Quality

- STRONG: All three areas enriched with high-confidence recommendations.
  Task is implementation-ready.
- ADEQUATE: Most areas enriched. Some gaps due to low confidence.
  Task is implementable with minor research.
- WEAK: Significant gaps remain. Recommend running specific skills
  separately for deeper analysis.

## Output Format

## Task Forge Synthesis

**Quality**: {STRONG|ADEQUATE|WEAK}
**Conflicts resolved**: {N}
**Recommendations kept**: {N} of {total}
**Domain skills included**: {list or "none"}

### Conflicts Resolved
| # | Conflict | Resolution | Precedence Rule |

### Testing Strategy
{complete section content}

### Implementation Guidance Addendum
{content to append}

### Documentation Requirements
{complete section content}

### Performance Considerations
{content, if applicable}

### Recommended Skills
Invoke these skills during and after implementation for best results.

| Skill | When to Invoke | Why |
|-------|---------------|-----|
| `/skill-name` | {during/after implementation — specific trigger} | {what it catches or validates} |

### Filtered Out
| # | Agent | Recommendation | Reason Dropped |
```

---

## Human Gate

Present synthesis summary to user:

```
## Task Forge — Enrichment Complete

Task: {id} — {title}
Complexity: {level} | Quality: {STRONG|ADEQUATE|WEAK}
Agents: Testing, Implementation, Documentation
Domain skills: {list or "none"} | Conflicts resolved: {N}

### Testing Strategy (new)
  - N unit, N property, N parameterized (rstest), N other (fuzz/kani/sim)

### Implementation Guidance (additions)
  - Allocation tier: {HOT|WARM|COLD}
  - Key constraints: {list}

### Documentation Requirements (new)
  - N type docs, N function docs, N module docs

### Recommended Skills (new)
  - During: {list of skills to invoke during implementation}
  - After:  {list of skills to invoke after implementation}

Options:
  - "approve" — apply all enrichments
  - "approve testing,implementation" — apply specific sections only
  - "edit" — show full enrichment text for manual editing
  - "skip" — discard enrichments, keep original task
  - "review" — also run /review-task on the enriched task
```

---

## Phase 4 — Integration

After user approval:

1. Read current task: `bd show <task-id>`
2. Merge enrichment sections into description:
   - **Testing Strategy**: Insert after "Code References" section
   - **Implementation Guidance Addendum**: Append to existing "Implementation Guidance"
   - **Documentation Requirements**: Insert after "Testing Strategy"
   - **Performance Considerations**: Replace or insert after "Documentation Requirements"
   - **Recommended Skills**: Insert after "Acceptance Criteria", before "Pointers"
3. Remove addressed `[NEEDS ENRICHMENT]` markers
4. Update: `bd update <task-id> --description="$ENRICHED_DESC"`
5. Add metadata footer: `<!-- task-forge: skills=[...] date=YYYY-MM-DD -->`
6. If user chose "review": invoke `/review-task <task-id>`

### Validation Before Updating

- No enrichment section contradicts "Desired State"
- All file paths in enrichment sections exist in the codebase
- No banned comment patterns in enrichment text
- Test code sketches reference correct types and imports

---

## Phase 5 — Output

```
Task: {id} — {title}
Status: Enriched | Quality: {STRONG|ADEQUATE|WEAK}

Sections Added/Updated:
  Testing Strategy     — {N} tests specified
  Implementation       — {N} recommendations
  Documentation        — {N} doc items
  Performance          — {N} constraints (if applicable)
  Recommended Skills   — {N} skills ({M} during, {K} after)

Next: bd update {id} --status=in_progress
  Or: /review-task {id}
```

---

## Error Handling

| Failure | Behavior |
|---------|----------|
| `/create-task` fails (Phase 0) | Report error, stop. |
| 1 enrichment agent fails (Phase 2) | Proceed with remaining agents. Note gap. |
| 2+ agents fail (Phase 2) | Report failure, offer to run survivors alone or abort. |
| Domain skill fails (Phase 2) | Proceed without it. Record in synthesis. |
| Synthesizer fails (Phase 3) | Present enrichment reports raw. User picks what to apply. |
| `bd update` fails (Phase 4) | Print enriched description for manual application. |

## Idempotency

The metadata footer tracks dispatched skills. On re-invocation, skip
already-dispatched skills unless task description changed (hash comparison).

## Relationship to Existing Skills

```
/task-forge = /create-task + classification + enrichment + synthesis
                                  |
                                  +-- embeds: /test-strategy methodology
                                  +-- embeds: /doc-rigor methodology
                                  +-- dispatches: domain skills (perf, dist-sys, unsafe, etc.)
                                  +-- recommends: implementation skills for the picking-up agent
                                  +-- optionally invokes: /review-task (validation)
```

Enrichment agents embed skill methodologies directly in their prompts
(same pattern as `/review-pipeline` embedding `/review-dispatch` in Agent A).
Domain skills are dispatched as parallel agents using the scoped prompt from
`/review-task` Phase 1.5.