---
id: T-362
name: "Auto-generate documentation articles from Component Fabric"
description: >
  Inception: Auto-generate documentation articles from Component Fabric

status: work-completed
workflow_type: inception
owner: human
horizon:
tags: []
components: []
related_tasks: []
created: 2026-03-08T21:55:31Z
last_update: '2026-06-11T22:24:19Z'
date_finished: 2026-03-09T08:49:51Z
target_blast_radius: 3   # T-2193 migration default (M=small-subsystem floor)
voi_score: 0.5            # T-2193 migration default (medium)
bvp_scores_proposed:
  - ts: '2026-06-11T22:24:19Z'
    estimator: bvp-estimator-v1-heuristic
    scores:
      D1: 2
      D2: 2
      D3: 2
      D4: 2
      F-RECALL: 2
      F-ORCH: 2
      F3: 2
      F1: 2
      F2: 2
    rationale: D1=2 (no-signal); D2=2 (no-signal); D3=2 (no-signal); D4=2 
      (no-signal); F-RECALL=2 (no-signal); F-ORCH=2 (no-signal); F3=2 
      (no-signal); F1=2 (no-signal); F2=2 (no-signal)
    rubric_sha: e4a00f38e801
---

# T-362: Auto-generate documentation articles from Component Fabric

## Problem Statement

127 components in the fabric, only 24 linked to 7 hand-written articles. 103 components have no documentation beyond a purpose field — 60% of which are broken/placeholder. New components get registered but never documented. We need a system that generates documentation automatically from existing structured data (cards, source code, CLAUDE.md, episodic memory).

## Assumptions

1. Component cards + source headers + CLAUDE.md contain enough data for useful reference docs — VALIDATED (agent 2: 80% mechanical extraction)
2. Existing framework patterns (episodic.sh, handover.sh) can be extended for doc generation — VALIDATED (agent 3: heredoc assembly + embedded Python)
3. Deep-dive articles follow a consistent template that can be parameterized — VALIDATED (agent 1: 4-section pattern, ~103 lines)
4. 60% of purpose fields need fixing before generation produces quality output — VALIDATED (agent 2)

## Exploration Plan

1. ~~Analyze existing article structure~~ — Done (agent 1): 4-section template identified
2. ~~Survey available data in fabric~~ — Done (agent 2): 80/20 mechanical/judgment split
3. ~~Check existing generation patterns~~ — Done (agent 3): heredoc + Python proven
4. Design two-layer system — Done: see `docs/reports/T-362-auto-doc-generation.md`

## Technical Constraints

- No external API dependencies for Layer 1 (mechanical generation)
- Layer 2 (article generation) needs LLM access — can output prompt files as fallback
- Generation must be idempotent (re-run produces same output for unchanged inputs)
- Must not modify source code or component cards (read-only generation)

## Scope Fence

**IN:** Design the auto-generation system, identify build tasks, go/no-go decision.
**OUT:** Actually building the generators (spawn as separate build tasks).

## Acceptance Criteria

- [x] Problem statement validated
- [x] Assumptions tested (3 research agents)
- [x] Go/No-Go decision made

## Go/No-Go Criteria

**GO if:**
- Layer 1 can generate useful reference docs from current card data — CONFIRMED
- Generation is idempotent — design ensures this (deterministic extraction)
- Generated docs integrate with Watchtower — CONFIRMED (markdown2 already available)

**NO-GO if:**
- Card data too sparse for basic reference docs — NOT the case (deps are 100% complete)
- Generation > 5 min for all 127 components — NOT the case (simple extraction)
- Output quality worse than reading source — NOT the case (aggregates multiple sources)

## Verification

test -f docs/reports/T-362-auto-doc-generation.md

## Decisions

**Decision**: GO

**Rationale**: All assumptions validated by 3 research agents. Two-layer design: Layer 1 (mechanical reference docs) covers 80% of value, Layer 2 (AI-assisted articles) adds narrative depth. Prerequisite: fix 60% broken purpose fields. See docs/reports/T-362-auto-doc-generation.md

**Date**: 2026-03-08T22:03:13Z
## Decision

**Decision**: GO

**Rationale**: All assumptions validated by 3 research agents. Two-layer design: Layer 1 (mechanical reference docs) covers 80% of value, Layer 2 (AI-assisted articles) adds narrative depth. Prerequisite: fix 60% broken purpose fields. See docs/reports/T-362-auto-doc-generation.md

**Date**: 2026-03-08T22:03:13Z

## Updates

<!-- Auto-populated by git mining at task completion.
     Manual entries optional during execution. -->

### 2026-03-08T22:03:13Z — inception-decision [inception-workflow]
- **Action:** Recorded inception decision
- **Decision:** GO
- **Rationale:** All assumptions validated by 3 research agents. Two-layer design: Layer 1 (mechanical reference docs) covers 80% of value, Layer 2 (AI-assisted articles) adds narrative depth. Prerequisite: fix 60% broken purpose fields. See docs/reports/T-362-auto-doc-generation.md

### 2026-03-09T08:49:51Z — status-update [task-update-agent]
- **Change:** status: started-work → work-completed

## Reviewer Verdict (v1.5)

- **Scan ID:** R-3123f605
- **Timestamp:** 2026-06-02T15:02:22Z
- **Catalogue:** v1.3-seed
- **Overall:** PASS
- **Needs Human:** no
- **Findings:** none
