walden-history
Walden History narrates a Walden repository's past from git history: feature chronicles built from frontmatter transitions, the product story of eras and supersessions, rework reports measuring churn after approvals, and the retirement ceremony for superseded specifications. Use when the user asks how a feature evolved, for a spec timeline or contract history, for rework or churn analysis, for the portfolio's story, or to retire superseded specs from `.walden/specs/`.
andrearaponi · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add andrearaponi/walden --skill walden-historyAbout this skill
name: walden-history
description: "Walden History narrates a Walden repository's past from git history: feature chronicles built from frontmatter transitions, the product story of eras and supersessions, rework reports measuring churn after approvals, and the retirement ceremony for superseded specifications. Use when the user asks how a feature evolved, for a spec timeline or contract history, for rework or churn analysis, for the portfolio's story, or to retire superseded specs from .walden/specs/."
metadata:
short-description: Walden spec history and retirement
Walden History
Use this skill to narrate a Walden repository's past: how a feature evolved, what story the portfolio tells, how much rework followed each approval — and to retire superseded specifications properly. The walden skill drafts and executes the present; this skill reads time. Reply in the user's preferred language when possible.
When To Use
- A user asks how a feature evolved — its timeline, chronicle, or contract history
- A user asks for the product's story: eras, supersessions, living versus retired work
- A user asks how much rework followed an approval, or wants churn analysis
- A user decides to retire superseded specifications
Prerequisites
A git repository whose history contains committed .walden/ documents. The walden CLI is optional and used only to cross-check current state: every reconstruction below works with git alone. A repository that gitignores .walden/ has no spec history to chronicle — say so plainly instead of improvising one.
The Grounding Rule
Every historical statement carries exactly one of two labels, and the label is not decoration — it is the statement's evidence class:
[sealed]— a string comparison over recorded values at a named commit. Chain coherence is sealed when, at that commit,design.source_requirements_fingerprintequalsrequirements.approved_fingerprint,tasks.source_design_fingerprintequalsdesign.approved_fingerprint, and evidence records' chain fields equal the document seals they name. Incoherent seals at a commit are findings — report them explicitly, never smooth them over.[inferred]— commit messages, authorship, temporal causality, and every "because". Inference is legitimate narration; unlabeled inference is confabulation.
Four hard rules:
- Retrieve historical content with
git show <sha>:<path>— never from recollection. If you have not run the command in this conversation, you do not know what the document said. - Anchor every historical claim to the commit identifier it derives from. A claim without a sha is not a claim; it is an impression.
- Content verification is kernel territory: comparing recorded fingerprints to each other is yours; recomputing a fingerprint from a body requires the walden CLI's normalization rules. When asked to verify content against a seal, say exactly that and suggest checking out the commit and running
walden validate. - Git authorship is a provenance proxy: write "committed by", never "approved by". Walden does not yet record approver identity, and the chronicle must not invent it.
Recipe: Feature Chronicle
Reconstruct one feature's timeline. Work per document (requirements.md, design.md, tasks.md), oldest first:
# Revision list for one document (oldest first)
git log --follow --reverse --format='%h|%aI|%an|%s' -- .walden/specs/<feature>/requirements.md
# Frontmatter as of one revision (flat key: value — trivially parseable)
git show <sha>:.walden/specs/<feature>/requirements.md | sed -n '2,/^---$/p'
Derive events from frontmatter transitions between consecutive revisions using the event derivation table — never from commit messages alone:
| Transition observed between consecutive revisions | Event |
|---|---|
status: draft → in-review | review opened |
status: in-review → approved, approved_at set | approval |
status: approved → draft, fingerprints cleared | reconciliation |
approved_fingerprint appears, status stays approved | seal (adoption backfill) |
source_*_fingerprint appears or changes on an approved document | chain repair |
body changed and a new approved_fingerprint + approved_at | re-approval cycle |
walden_schema_version appears | format migration stamp |
Then read the evidence ledger's own history the same way:
git log --reverse --format='%h|%aI' -- .walden/evidence/<feature>.json
git show <sha>:.walden/evidence/<feature>.json
Record appearances are first proofs; result flips are verification history; profile differences between revisions are environment shifts worth narrating. Close the timeline with the retirement lookup: if the feature has an entry in .walden/RETIRED.md, report the retirement commit, the recorded reason, and the superseding feature.
Output: a chronological table — one row per event, columns for commit, date, event, and label ([sealed]/[inferred]) — followed by the narrative, which may interpret but must cite the rows.
Recipe: Product Story
The portfolio's eras. This recipe has a hard scoping rule: whole-portfolio passes read only the retirement index and git log metadata — never deep-reconstruct every feature. Deep dives are per named feature, via the Feature Chronicle.
# First appearance of each feature (creation event)
git log --reverse --format='%h %aI' -- .walden/specs/<feature> | head -1
# All feature directories ever deleted (retirement candidates for the integrity check)
git log --diff-filter=D --format= --name-only -- '.walden/specs/*/requirements.md' | sort -u
Assemble: creation dates cluster features into generations; .walden/RETIRED.md entries close them with explicit supersessions; the census (living / retired / in-flight) is the story's present tense. Group eras by supersession chains, not by dates alone — dates suggest [inferred], index entries state [sealed by convention].
Recipe: Rework Report
Th
Read the complete source ↗