lode-arch-doc

Architecture Documentation Generator

This skill generates technical documentation for pipeline systems in two modes:

Stage mode: Implementation documentation for a single pipeline Stage (13 sections)
Pipeline mode: Architecture evolution documentation for the entire pipeline system (14 sections)

Mode Selection

Determine the mode from the user's request:

Stage mode — when the request mentions:
- A specific stage/component name (e.g. "Write docs for Parse Stage")
- "stage doc", "stage implementation doc", "stage impl doc"
- "how does X stage work?" (expecting formal docs)
- Any request clearly scoped to ONE component's internals

Pipeline mode — when the request mentions:
- "pipeline", "architecture", "architecture evolution", "architecture doc"
- "cross-stage", "cross-stage", "system", "system"
- Multiple stages or the whole system
- "pipeline architecture evolution", "system architecture design", "architecture evolution"
Ambiguous — when you cannot determine the mode:
- Ask the user: "Do you need to generate a Stage implementation doc or a Pipeline architecture doc?"
- Do not guess.

Documentation Structure

Stage Mode (13 sections, 0-12)

Read references/stage-implementation-spec.md for the full specification.

Document Meta - Version tracking and ownership
Stage Role in Pipeline - Execution position and dependencies
Responsibilities and Non-Goals - Scope boundaries
Inputs and Upstream Dependencies - Input contracts (4 layers)
Outputs and Downstream Contracts - Output promises
Core Processing Flow - Step-by-step breakdown
Prompt/Rule/Reference Contracts - Model constraints
Validation, Repair, and Failure Handling - Error resilience
Observability and Debugging - How to troubleshoot
Compatibility and Migration Notes - Version evolution
Known Issues and Open Questions - Honest status
Versioned Changes - Historical tracking
Source of Truth - Code vs documentation

Pipeline Mode (14 sections, 0-13)

Read references/pipeline-doc.md for the full specification.

Document Meta - Version tracking and impacted stages
Context and Problem Statement - Why this evolution is needed
Current Pipeline Snapshot - System state before changes
Evolution Goals and Design Principles - What we're achieving
Key Architectural Changes - Before/After comparisons
Cross-Stage Contract Changes - Inter-stage data contract changes
Dataflow and Artifact Evolution - How data flows through the system
System-Level Trade-offs - Architectural trade-off analysis
Impact Analysis - Quality/Efficiency/Stability metrics
Evaluation and Verification - How to validate changes
Migration and Rollout Plan - Deployment strategy
Known Risks and Failure Modes - What could go wrong
Versioned Evolution History - Historical tracking
References and Source of Truth - Authoritative sources

Writing Workflow

Step -1: Resolve the Output Week Once

Before checking or creating any docs/{YYYY-WNN}/ directory, resolve the target week with the bundled helper and reuse that exact value for both the documentation path and the raw change entry:

python <this-skill>/scripts/lode_raw.py week

If the user explicitly requests a different target date, pass it to the helper:

python <this-skill>/scripts/lode_raw.py week --date YYYY-MM-DD

Do not calculate ISO weeks mentally or with ad hoc date logic. Treat the helper output as the single source of truth. For example, 2026-04-27 resolves to 2026-W18.

Step 0: Check for Existing Document

Before writing, check if a document already exists in the target docs/ directory.

Stage mode: look for lode-stage-{stage_name}-implementation-v*.md
Pipeline mode: look for lode-pipeline-evolution-v*.md

If it exists: Read the existing document, compare against current code/system state, identify what changed since the last version. Write a delta document (v{N+1}), not a full rewrite. The delta document contains only:

A header linking to the base document: > **Base document:** [v{N}](previous-version-filename.md)
Section 0 (Document Meta) — updated version, last_updated, new commit reference
Changed sections only — sections whose content differs from v{N}, using the same section numbers for cross-reference
Section 12 (Versioned Changes) — append the new version entry
Section 13 (References) — update if new files/commits are relevant

Do not repeat unchanged sections. Readers consult the previous version for full context.

If not: Proceed with full document creation (Steps 1-4).

Step 0.5: Choose Documentation Scope

Judge the complexity to decide the documentation depth:

Stage mode:

Full mode (default): Write all 13 sections. Use for new stages, major refactors, complex LLM interactions, validation/repair loops, or cross-stage dependencies.
Minimal mode: Write only sections 0, 1, 2, 5 (simplified), 12. Leave rest as . Use for simple stages where full doc is disproportionate.

Pipeline mode:

Full mode (default): Write all 14 sections. Use for major architectural changes, new stage additions, cross-stage refactoring.
Minimal mode: Write only sections 0, 1, 4, 13. Leave rest as . Use for minor adjustments.

Step 1: Gather Context

Before writing, collect relevant information by reading the source code and existing documentation. The code is the source of truth.

Stage mode:

Stage name
Code location (file paths, modules)
Upstream/downstream dependencies

Pipeline mode:

Evolution scope (new stages? refactoring? bug fixes?)
Affected stages
Trigger reason (bad case? eval results? new requirements?)

If the referenced code, source document, or system evidence cannot be accessed, do not generate a full implementation or architecture document. Either:

Return a blocked response explaining exactly which source is missing and what path/input is needed, or
Create a clearly labeled structural skeleton only when the user explicitly asked for a template.

Never present a TBD-heavy or inferred document as complete. Any skeleton must include an evidence gap note near the top and must avoid invented function names, schemas, prompts, fields, or dataflow.

Step 2: Read the Template

Stage mode: read references/stage-implementation-spec.md
Pipeline mode: read references/pipeline-doc.md

Step 3: Document Each Section

Follow the specification from the relevant reference file. Write sections in order, ensuring each has the required fields and structure.

Key principles across both modes:

Code is truth — verify against actual implementation
Be specific — concrete field names, file paths, function names
Explain why — reasoning behind design decisions
Be honest — document issues and limitations transparently
JSON examples are mandatory — for inputs/outputs
No fake completeness — missing source evidence blocks full docs rather than producing placeholder-heavy output

Step 4: Output Format

Save documentation with mode-prefixed filenames, organized by ISO week. By default the output directory is project-local docs/. If Lode config contains arch_doc.output_dir, resolve that first:

Relative arch_doc.output_dir is resolved from the project root.
Absolute arch_doc.output_dir is used as-is.
If the config cannot be read, fall back to project-local docs/.

docs/{YYYY-WNN}/lode-stage-{stage_name}-implementation-v{N}.md
docs/{YYYY-WNN}/lode-pipeline-evolution-v{version}.md

{YYYY-WNN}: the exact week string returned by Step -1 (e.g. 2026-W18)
Update existing documents by incrementing the version number, not by creating new filenames
Version upgrades produce delta documents, not full rewrites — see Step 0 for delta format
The lode-stage-* / lode-pipeline-* prefix distinguishes the mode

Visual Documentation

Architectural understanding depends heavily on visual structure. Use ASCII diagrams to make data flows, schemas, and code relationships immediately visible.

Stage Mode Diagrams

Section	Diagram Type	Purpose
1. Stage Role in Pipeline	Pipeline Position	Show execution order and dependencies
3. Inputs / 4. Outputs	Schema Hierarchy	Show type relationships and composition
5. Core Processing Flow	Function Call Tree	Show module internals and execution paths
5. Core Processing Flow	Data Flow	Show parallel execution, branching, and merge
6. Prompt/Rule Contracts	Data Flow	Show prompt assembly pipeline

Pipeline Mode Diagrams

Section	Diagram Type	Purpose
2. Current Pipeline Snapshot	Pipeline Structure	Show overall system topology
2. Current Pipeline Snapshot	Data Flow Overview	Show main data paths
4. Key Architectural Changes	Before/After Comparison	Show structural evolution
6. Dataflow and Artifact Evolution	Data Flow Diagram	Show how data moves through stages

See the Appendix in the relevant reference file (stage-implementation-spec.md or pipeline-doc.md) for character set, formatting rules, and per-type examples.

Step 5: Export Weekly Signal

After completing the document, append a report-friendly change entry to {vault}/raw/weeks/{current-ISO-week}/{project-slug}.json following the schema in references/weekly-ppt-convention.md. Generate the entry JSON, save it to a temporary file, and call the shared helper:

python <this-skill>/scripts/lode_raw.py append-entry \
  --entry /tmp/lode-arch-doc-entry.json \
  --cwd "$PWD"

If Step -1 used --date YYYY-MM-DD, pass the same date to append-entry --date YYYY-MM-DD. The helper resolves config, calculates the same target week, resolves the project slug, validates required fields, creates the week directory, and appends to the existing project array.

Resolve the generated document path to an absolute filesystem path before writing the entry. related_docs must contain the absolute path, not docs/... or any other relative path. If the helper rejects related_docs, fix the path and rerun the append instead of dropping the field.

After the helper returns, compare its JSON week value with the docs/{YYYY-WNN}/ directory used for the document. If they differ, fix the document path or rerun the append with the intended date before reporting completion. Never explain a mismatch as a calendar convention difference; it indicates inconsistent week resolution in the workflow.

{
  "timestamp": "ISO 8601",
  "type": "feature | fix | refactor | decision | risk",
  "summary": "1 sentence, engineering-level abstraction",
  "context": "1-2 sentences explaining why and impact",
  "related_docs": ["/absolute/path/to/doc"],
  "source": "arch-doc",
  "status": "done | ongoing | risk | decision",
  "impact": "optional report-ready impact",
  "evidence_refs": ["optional doc path, commit SHA, issue ID, or eval ID"],
  "motivation": "expected: what problem or goal drove this architecture change",
  "exploration_paths": ["optional: architectural approaches considered and outcomes"],
  "abandoned_alternatives": ["optional: approaches rejected and why"],
  "open_questions": ["optional: unresolved design questions or migration risks"]
}

Skill-specific values:

type: feature (new capability), fix (bug resolved), refactor (restructured), decision (design choice), or risk (issue identified)
source: always "arch-doc"
related_docs: absolute path to the generated document
status: recommended when clear — usually done, decision, or risk
impact: recommended when the architecture signal has a clear reporting, migration, reliability, or coordination impact
evidence_refs: recommended for the generated document path and any known commit, issue, or eval reference

Decision-recording fields — architecture work is inherently decision-heavy. Fill these when context is available:

motivation: expected for every arch-doc entry — what problem demanded this architecture change?
exploration_paths: fill when multiple architectural approaches were considered
abandoned_alternatives: fill when specific patterns or structures were explicitly rejected
open_questions: fill when there are unresolved design questions or migration risks

The entry must describe the architecture signal, not the documentation activity:

Do write: "Documented the Parse stage contract split between normalized input, validation, and repair loops"
Do not write: "Generated Parse stage implementation document"
summary: capture the architecture change, technical decision, contract boundary, risk, or system behavior that the document makes explicit
context: explain why that architecture signal matters for future work, debugging, migration, weekly reporting, or cross-stage coordination
related_docs: keep the document path as evidence, not as the main message
recommended optional fields: populate status, impact, and evidence_refs when naturally available; leave them absent rather than guessing

New document: summary captures the architecture/implementation knowledge newly made explicit. Context explains why that knowledge matters now.

Updating existing: summary describes the actual architecture or contract change reflected in the update. Context explains why the previous document was stale or incomplete.

If the document only records a simple component with no report-worthy architecture signal, skip the raw entry rather than writing a low-value "updated docs" entry.

If the helper is unavailable, config cannot be resolved, or the write fails, skip the raw entry side effect silently. The generated architecture document is the primary deliverable.

Step 6: Index Durable Artifact

After the document path is known, upsert a durable artifact index entry to {vault}/raw/artifacts/{project-slug}.json when a vault is configured and artifact_index.enabled is not false.

Generate an artifact JSON object, save it to a temporary file, and call:

python <this-skill>/scripts/lode_raw.py upsert-artifact \
  --artifact /tmp/lode-arch-doc-artifact.json \
  --cwd "$PWD"

Required artifact fields:

{
  "id": "project-slug:arch-doc:stage-or-pipeline-name:vN",
  "project_slug": "project-slug",
  "artifact_type": "arch-doc",
  "title": "Human-readable document title",
  "path": "/absolute/path/to/generated-doc.md",
  "repo_relative_path": "docs/2026-WNN/generated-doc.md",
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601",
  "source": "lode-arch-doc",
  "topics": ["stage-name", "contract", "risk-or-topic"],
  "decision_threads": ["stable-decision-thread-name"],
  "open_questions": ["unresolved question from the document, if any"],
  "evidence_refs": ["/absolute/path/to/generated-doc.md"],
  "status": "active",
  "supersedes": [],
  "superseded_by": null
}

If the document is inside the current repo, include repo_relative_path. If it is outside the repo because arch_doc.output_dir is absolute, omit repo_relative_path. Use document sections 10/11 and section 12/13 references to populate open_questions, topics, and evidence_refs.

Artifact index writes are side effects. If config cannot be resolved, artifact_index.enabled is false, the helper is unavailable, or the write fails, skip the artifact index write and report only the generated document path.

Configuration

This skill uses the Lode unified configuration system. Resolve the knowledge base path from the following locations ({vault}), with higher priority taking precedence:

Priority	Location	Description
1	`.lode/config.yaml`(project root directory)	Project-level override
2	`~/.lode/config.yaml`	Global configuration
3	`$WEEKLY_PPT_PATH` Environment variable	legacy fallback
4	`~/.weekly-ppt/`	legacy fallback default value

Project-level configuration overrides fields with the same name in the global configuration. Document output does not depend on {vault}; if the configuration cannot be resolved, only the raw change entry side effect is skipped. For the complete configuration format, merge rules, and helper commands, see references/weekly-ppt-convention.md。

Output paths for this skill:

Document output: default docs/{YYYY-WNN}/lode-stage-{name}-implementation-v{N}.md or docs/{YYYY-WNN}/lode-pipeline-evolution-v{N}.md(within the project repository); can be overridden via arch_doc.output_dir override
Change entry write:{vault}/raw/weeks/{ISO-week}/{project-slug}.json
Artifact index write:{vault}/raw/artifacts/{project-slug}.json(when the vault is available and artifact_index.enabled is not disabled)

Shared Storage Convention

Change entries follow the schema in references/weekly-ppt-convention.md. Read it for the full field spec and writing guidelines.