Prompt Archaeology

Governing Axiom

This skill enacts the Endogenous-First axiom from MANIFESTO.md:

Session artifacts — scratchpads, commit messages, issue comments, session summaries — are endogenous knowledge. Mining them before reaching outward satisfies the axiom that existing system knowledge must be exhausted before generating new tokens.

It also enacts the Programmatic-First principle from AGENTS.md:

Constraints discovered interactively more than twice must be encoded programmatically before the third time. Prompt archaeology is the mechanism that catches constraints that survived two sessions interactively but were never promoted to a script, guide, or skill.

Implements: Issue #146 — Implement prompt archaeology as a post-sprint ritual

Governed by:

• AGENTS.md § Session-Start Encoding Checkpoint — archaeology findings feed the encoding checkpoint for the next sprint
• MANIFESTO.md Endogenous-First axiom — session artifacts are the first-order endogenous source

Companion skill: session-retrospective — retrospective harvests this session's lessons; archaeology mines older sessions. They feed each other: retrospective findings accumulate as future archaeology targets.

Foundation documents:

• docs/research/scratchpad-architecture-maturation.md — R1 recommendation: docs/sessions/ curated archive (the primary persistent archaeology substrate)
• docs/guides/session-management.md — session lifecycle this skill extends

2. What Is Prompt Archaeology

Prompt archaeology is the practice of systematically reviewing prior session artifacts to recover knowledge that was generated interactively but never encoded into the substrate.

Every agent session produces ephemeral artifacts — scratchpad entries, commit message bodies, issue comments, and improvised workarounds. Most are written under context-window pressure and forgotten. Prompt archaeology treats these artifacts as a corpus to mine.

Three categories of recoverable knowledge:

Canonical example: During sprint Milestone-9, the pattern "write body to temp file and use --body-file" was performed interactively in three sessions before it was encoded as an AGENTS.md guardrail. Archaeology on those three scratchpads would have caught it after the second session.

Anti-pattern: Running archaeology as a box-ticking exercise without gap-analysing against the existing substrate. Surface-level "we did X" summaries are not findings — the signal is "we did X because Y, and Y is not yet encoded anywhere."

3. When to Run

Primary trigger — post-sprint (recommended):

Run prompt archaeology after every milestone completion, before the next sprint's planning session. The correct ordering is:

Sprint close → session-retrospective (current session) → prompt archaeology (prior sessions) → next sprint planning

Secondary trigger — familiar-problem signal:

Run archaeology when you encounter a problem that feels familiar but no substrate guidance exists. The absence of a guide despite a sense of familiarity is evidence that prior sessions solved it interactively without encoding.

Do NOT run if:

• Context window is under pressure — note the gap in the scratchpad and schedule for next session.
• The branch has no prior session artifacts (first session on a new branch).
• You are mid-phase — wait for a phase boundary.

4. Artifacts to Mine

Mine these sources in priority order — highest-signal first:

4.1 Active Scratchpads (.tmp/<branch-slug>/*.md)

Gitignored; available only during the current session. Mine before the session closes or the window compacts.

ls .tmp/<branch-slug>/
cat .tmp/<branch-slug>/<date>.md | grep -A5 "## Session Summary\|## Retrospective\|## Executive Handoff"

Key sections to target: ## Session Summary, ## Executive Handoff, ## Retrospective — *, ## Pre-Compact Checkpoint.

4.2 Archived Session Summaries (docs/sessions/)

Committed to git per R1 of scratchpad-architecture-maturation.md. Naming convention: YYYY-MM-DD-<branch-slug>-summary.md.

ls docs/sessions/
grep -l "<branch-slug>" docs/sessions/*.md | xargs grep "Open questions\|Key findings"

These are the highest-quality archaeology targets: curated, structured, and querable via scripts/query_docs.py.

4.3 Commit Messages (git log)

Commit message bodies (not just subject lines) often carry decision rationale written under time pressure and never promoted to a guide.

git --no-pager log --oneline --since="2 weeks ago"
git --no-pager log --format="%H %s%n%b" --since="2 weeks ago" | grep -v "^$"

Look for: # Why:, Note:, Fixes, Workaround:, rationale sentences in commit bodies.

4.4 Issue Comments (gh issue view)

Issue comments with ## Session Summary or ## Phase N Complete bodies often contain the richest decision rationale, written at phase close.

gh issue list --state all --limit 50 --json number,title | jq '.[] | "\(.number) \(.title)"'
gh issue view <number> --comments | grep -A20 "Session Summary\|Phase.*Complete\|Key finding"

Mine closed issues from the relevant milestone — their session-close comments are archaeology gold.

5. Procedure

Step 1 — Scan

List all artifacts for the target branch or sprint. Build an artifact inventory:

## Archaeology Scan — <branch> — <date>

### Artifacts found
- Scratchpads: .tmp/<branch>/<date1>.md, <date2>.md
- Session summaries: docs/sessions/<summarised>.md (if present)
- Commits mined: git log --oneline <from>..<to> (N commits)
- Issues reviewed: #NN, #NN, #NN

Write this to the active scratchpad under ## Archaeology — <sprint-name>.

Step 2 — Extract

For each artifact, note raw findings without filtering. Use a consistent structure:

### Finding — <brief label>
**Source**: <artifact path or issue #, line range>
**Category**: decision-rationale | pattern | interactive-constraint
**Raw text**: "<verbatim quote or close paraphrase>"
**Why it matters**: <one sentence — what would be lost if not encoded>

Step 3 — Gap-Analyse Against Substrate

For each finding, check whether it is already encoded:

grep -r "<keyword>" AGENTS.md docs/guides/ .github/skills/ .github/agents/

Mark each finding:

• ENCODED — already in substrate; discard
• PARTIAL — implied but not stated explicitly; encoding gap
• ABSENT — not in substrate; encoding required

Route only PARTIAL and ABSENT findings forward.

Step 4 — Route to Encoding Layer

Each unencoded finding maps to exactly one encoding layer:

Write a routing table in the scratchpad:

### Routing Plan
| Finding | Category | Layer | Owner | Issue? |
|---------|----------|-------|-------|--------|
| Heredoc silently corrupts backticks | constraint | AGENTS.md guardrail | Exec Docs | existing |
| Compression trick: bullets-only return | pattern | session-retrospective SKILL | Exec Docs | new |

Step 5 — Commit the Encoding

Delegate each routing entry to the correct executive agent and track encoding commits. A finding is closed only when a commit lands — scratchpad notes alone do not close the encoding circuit.

When all PARTIAL and ABSENT findings have been encoded and committed:

• Update the routing table: mark each row COMMITTED: <sha>
• Write a ## Archaeology Close — <sprint-name> — <date> section in the scratchpad
• If archaeology produced ≥3 new encodings, run session-retrospective on the archaeology session itself

6. Relationship to session-retrospective

They form a feedback loop: every session-retrospective creates an artifact that becomes an archaeology target in the next sprint. Every archaeology finding that surfaces an un-encoded pattern becomes a session-retrospective action item.

The encoding circuit does not close until a commit lands. Both skills exist to ensure the circuit always closes.

Deliverable