# Tech Log Document Pipeline Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.

**Goal:** Build a self-contained codebase-to-Tech-Log documentation pipeline with project-scoped analysis, grounded root-tree decomposition, evidence tooling, and editorial skills.

**Architecture:** `/shared/codebase/<project>` is the source. `/shared/document-detail/<project>` owns deep analysis and the root tree. `/shared/Tech-Log-Document/<project>` owns publishable record drafts and assets. Local skills and templates make all stages independent from historical workspaces.

**Tech Stack:** Markdown, JSON, Python 3 standard library, SVG, shell-based verification.

**Spec:** `docs/superpowers/specs/2026-08-28-tech-log-document-pipeline-design.md`

## Global Constraints

- No runtime dependency on any legacy document workspace.
- Root-tree nodes require source anchors and readiness state.
- No invented incidents, decisions, measurements, first-person experience, or technical selection reasons.
- Raw evidence precedes rendered evidence.
- Terminal SVGs must derive from actual command output and redact obvious credentials.
- Editorial refinement preserves technical facts and evidence semantics.

---

### Task 1: Workspace contract and templates

**Files:**
- Create: `/shared/Tech-Log-Document/AGENTS.md`
- Create: `/shared/Tech-Log-Document/README.md`
- Create: `/shared/document-detail/README.md`
- Create: `/shared/document-detail/_templates/*`
- Create: `/shared/Tech-Log-Document/_templates/project/*`

- [x] Encode directory ownership, stage boundaries, and safety rules.
- [x] Add project analysis state, source-index, final-document, and root-tree templates.
- [x] Add Tech Log project output/state templates.
- [x] Verify all required paths exist.

### Task 2: Root-tree and Tech Log generation skill

**Files:**
- Create: `.agents/skills/writing-tech-log-from-analysis/SKILL.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/references/record-kinds.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/references/root-tree-contract.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/references/body-syntax.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/references/evidence-and-diagrams.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/references/review-checklist.md`
- Create: `.agents/skills/writing-tech-log-from-analysis/templates/*`

- [x] Distill the historical Tech Log format into self-contained references.
- [x] Make source provenance/readiness gates mandatory.
- [x] Encode different output contracts for Case/Reference/Open Question/Decision.
- [x] Add static verification for forbidden legacy-path dependencies and required skill sections.

### Task 3: Korean technical-writing editorial skill

**Files:**
- Create: `.agents/skills/humanizing-korean-tech-writing/SKILL.md`
- Create: `.agents/skills/humanizing-korean-tech-writing/references/editorial-rules.md`
- Create: `.agents/skills/humanizing-korean-tech-writing/references/protected-content.md`
- Create: `.agents/skills/humanizing-korean-tech-writing/references/research-method.md`
- Create: `research/korean-tech-writing/README.md`

- [x] Encode content-preserving editorial scope.
- [x] Carry forward known AI-writing failure patterns without referencing their historical location.
- [x] Define how later public-blog research is distilled into the skill without copying a single writer's voice.
- [x] Verify protected-content and anti-fabrication rules are present.

### Task 4: Terminal evidence renderer via TDD

**Files:**
- Create: `tools/terminal-evidence/tests/test_render_terminal.py`
- Create: `tools/terminal-evidence/render_terminal.py`
- Create: `tools/terminal-evidence/README.md`

- [x] Write tests for XML escaping, metadata, line rendering, redaction, and truncation marker.
- [x] Run tests before implementation and confirm they fail because the renderer is missing.
- [x] Implement the minimal renderer using Python standard library.
- [x] Run tests and confirm they pass.
- [x] Render a sample from real command output and validate the SVG as XML.

### Task 5: Example root-tree contract

**Files:**
- Create: `/shared/document-detail/_examples/backend-clean-architecture/root-tree.md`

- [x] Encode the requested JPA feed topic tree as an explicitly marked structural example.
- [x] Add source/evidence/readiness metadata placeholders that make clear it is not claimed as newly analyzed evidence.
- [x] Verify the example conforms to the root-tree contract.

### Task 6: End-to-end static verification

**Files:**
- Create: `/shared/Tech-Log-Document/tools/verify_pipeline.py`
- Create: `/shared/Tech-Log-Document/tools/tests/test_verify_pipeline.py`

- [x] Write failing tests for required paths and forbidden legacy dependency strings.
- [x] Implement the verifier.
- [x] Run all tests.
- [x] Search the new pipeline for forbidden legacy-path references.
- [x] Print the final directory tree and verification summary.