donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
69556114391090fd567aaaf2da7e7fa2a838e004
document-haness/docs/_design/2026-08-28-tech-log-document-pipeline.md
T
DongHyeonkaandClaude Opus 5 b2963105a8 docs(keycloak-session-store): import the session-storage lab as a new project 
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>
2026-09-04 22:51:59 +09:00

5.0 KiB
Raw Blame History

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/*

  • Encode directory ownership, stage boundaries, and safety rules.

  • Add project analysis state, source-index, final-document, and root-tree templates.

  • Add Tech Log project output/state templates.

  • 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/*

  • Distill the historical Tech Log format into self-contained references.

  • Make source provenance/readiness gates mandatory.

  • Encode different output contracts for Case/Reference/Open Question/Decision.

  • 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

  • Encode content-preserving editorial scope.

  • Carry forward known AI-writing failure patterns without referencing their historical location.

  • Define how later public-blog research is distilled into the skill without copying a single writer's voice.

  • 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

  • Write tests for XML escaping, metadata, line rendering, redaction, and truncation marker.

  • Run tests before implementation and confirm they fail because the renderer is missing.

  • Implement the minimal renderer using Python standard library.

  • Run tests and confirm they pass.

  • 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

  • Encode the requested JPA feed topic tree as an explicitly marked structural example.

  • Add source/evidence/readiness metadata placeholders that make clear it is not claimed as newly analyzed evidence.

  • 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

  • Write failing tests for required paths and forbidden legacy dependency strings.

  • Implement the verifier.

  • Run all tests.

  • Search the new pipeline for forbidden legacy-path references.

  • Print the final directory tree and verification summary.

Reference in New Issue View Git Blame Copy Permalink