DongHyeonkaandClaude Opus 5
b2963105a8
The keycloak project ended with four open questions that design could not
settle. A two-VM lab was built to answer them by measurement, and this is
that material: 26 experiments, 125 raw command outputs, 22 browser captures.
Follows the import procedure in README.md.
source/ the originating repository verbatim — 78 documents, 28 SVGs,
8 manifests, plus .source-revision recording the commit
final/ the SSOT
document.md 729 lines written from the 29 experiment documents, not
concatenated: what was predicted, what was measured, and
where the measurement itself was wrong
evidence/raw 125 outputs, flattened to <experiment>__<file> because
the originals collided (01-baseline.txt appeared three
times) and the audit only globs the top level
evidence/meta one per raw file; command and exitCode are null and the
README says why rather than inventing them
evidence/browser 22 captures
assets/ three diagrams through techviz
.techviz/ their VizSpecs
A separate project rather than an addition to keycloak: the B-layer answers
that project's four questions, but the A, C and D layers are about cluster
failure, SSO and operations, and one document.md should hold one subject.
The four question records there can point here through 관계.
Recorded rather than papered over: only three of the 28 diagrams were
remade. The repository forbids hand-drawn SVG and forbids titles inside the
canvas; all 28 originals carry both, so converting them is redrawing, not
reformatting. They stay in source/ and the gap is written into the document.
verify-pipeline.py passes. audit-records.py reports no issues.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
101 lines
5.0 KiB
Markdown
101 lines
5.0 KiB
Markdown
# 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.
|