create-walkthrough

Generate honest, argumentative walkthrough documents for complex implementations. Not a status report or handoff document. A prosecution brief where the agent argues why an implementation should succeed, admits what could go wrong, and the user pokes holes.

This is a COLLABORATIVE skill. The agent does NOT write a walkthrough alone.

Why This Exists

A walkthrough caught two real bugs before a pipeline launch:

1. A false claim about a missing dependency (agent wrote it, agent believed it, user caught it)
2. A missing semantic quality check the deterministic assessment couldn't provide

The value isn't the document structure. It's:

• Collaboration: the human and a persona expert contribute BEFORE writing starts
• Risk-forcing: every change MUST have "what could still go wrong"
• Claim verification: every factual statement is audited against actual code
• User review surface: the document exists so the human can push back

Why Collaboration Is Non-Negotiable

An agent writing a walkthrough alone produces a monologue — it explains its own work to itself. The agent's blind spots become the walkthrough's blind spots. Real bugs were caught in the episodic-archiver v2 walkthrough not by the agent, but by the user reading critically. The interview and persona consultation exist to surface concerns the agent cannot see.

Incident (2026-02-13): Agent skipped interview + persona consultation for the episodic-archiver v2 walkthrough. Result: a technically correct but one-dimensional document that missed the user's concern about conversation prediction classifiers and the persona's expertise in user behavioral modeling. The walkthrough failed at its primary purpose — being a collaboration surface.

When to Use

Use /create-walkthrough when ALL of these are true:

• The system has failed before (at least one prior attempt)
• The implementation is complex (multi-file, multi-concern)
• You're about to launch or deploy (not still designing)
• The user needs to review and approve before proceeding

Do NOT use for:

• First-time implementations (use /plan instead)
• Simple features or bug fixes
• Agent-to-agent handoff (use /create-context instead)
• General project health (use /assess instead)

How It Differs

Pre-Flight Checklist (BLOCKING)

Before writing ANY walkthrough content, verify ALL of these:

If ANY gate is incomplete, STOP. Do not write the walkthrough.

The agent MUST NOT rationalize skipping gates:

• "I have deep session context" is NOT a reason to skip the interview
• "No persona is relevant" is NOT true — every implementation has a domain expert
• "The user didn't ask for persona input" is NOT relevant — the skill requires it

Workflow

Phase 1: Human Interview (MANDATORY — NO EXCEPTIONS)

ALWAYS ask the human. Even if you implemented the code yourself in this session. Even if you think you know the answers. The human sees things you don't.

Use /interview or AskUserQuestion to gather:

[
  {
    "id": "failures",
    "text": "What has failed in previous attempts? List specific failure modes.",
    "type": "text",
    "header": "Failures"
  },
  {
    "id": "concerns",
    "text": "What are you most worried about this time?",
    "type": "text",
    "header": "Concerns"
  },
  {
    "id": "constraints",
    "text": "What deployment constraints apply?",
    "header": "Constraints",
    "options": [
      {"label": "Single process only", "description": "No concurrent daemons"},
      {"label": "Must survive API outages", "description": "External dependency resilience"},
      {"label": "Unattended overnight", "description": "No human monitoring"},
      {"label": "Resource constrained", "description": "Memory/CPU/VRAM limits"}
    ],
    "multi_select": true
  },
  {
    "id": "scope",
    "text": "Which files/systems should the walkthrough cover?",
    "type": "text",
    "header": "Scope"
  },
  {
    "id": "persona",
    "text": "Which persona should review this? (Pick the domain expert most relevant to this system.)",
    "type": "text",
    "header": "Reviewer"
  }
]

Why this can't be skipped: The human's concerns shape the walkthrough's focus. Without asking, the agent writes about what IT thinks matters. The episodic-archiver v2 walkthrough missed the user's interest in conversation prediction classifiers because the agent never asked. The interview is how the human steers the walkthrough.

Minimum interview: If /interview is unavailable, use AskUserQuestion with at minimum these 3 questions:

1. "What are you most worried about with this implementation?"
2. "What should the walkthrough focus on — what do you need to be convinced of?"
3. "Which persona should review this? (e.g., Embry for user modeling, Brandon for SPARTA, Margaret for extraction)"

Also gather from automated sources:

• /memory recall for past failures, lessons, and assessments related to this system
• git log for recent changes and commit messages
• CONTEXT.md for current state documentation

Phase 1b: Persona Consultation (MANDATORY — NO EXCEPTIONS)

ALWAYS consult a persona. The user nominates one in the interview (Phase 1). If the user didn't specify, pick the most relevant domain expert yourself and confirm with the user: "I'll consult [Persona] — they have expertise in [domain]. Sound right?"

Use /ask consult <persona> with a summary of changes:

We're about to deploy [system]. Here's what changed:
1. [Change 1 — one sentence]
2. [Change 2 — one sentence]
3. [Change N — one sentence]

What concerns you? What are you satisfied with? What would you watch for
in the first hour of deployment?

Why this can't be skipped: Different personas surface different concerns. The agent may not realize that a design pattern is risky in a specific domain — but the persona will. Examples:

The persona's output becomes the "Expert Commentary" section of the walkthrough.

## Expert Commentary

**[Persona Name]** — [Role/Title]

> **What I'm satisfied with:**
> - [Specific thing persona approves, with domain reasoning]
> - [Another]
>
> **What concerns me:**
> - [Specific concern, grounded in persona's expertise]
> - [Another]
>
> **What I'd watch for in the first hour:**
> - [Observable metric or behavior the persona would monitor]

This transforms the walkthrough from "agent explains agent's work" to "domain expert reviews agent's work." The persona brings knowledge the agent may lack.

Rule: The persona consultation is GENERIC. Any persona from personas.yaml can be consulted. Do NOT build persona-specific logic into the skill.

Phase 2: Analyze the Implementation

Only proceed here after BOTH Phase 1 and Phase 1b are complete.

Read the actual code. For each significant change:

1. Identify what it replaces (the old approach that failed)
2. Understand the mechanism (how the new code works, line numbers)
3. Find the integration points (where it connects to existing code)
4. Assess the risk (what could go wrong with this specific change)
5. Cross-reference with interview (does this address the user's concerns?)
6. Cross-reference with persona (does this address the persona's concerns?)

Phase 3: Write the Walkthrough

Use this structure. All sections are REQUIRED.

The walkthrough MUST incorporate:

• User's concerns from the interview (Phase 1)
• Persona's concerns and satisfactions from the consultation (Phase 1b)
• Memory recall results showing prior failures and lessons

# [System Name] v[N]: Honest Walkthrough

**Date:** YYYY-MM-DD
**File(s):** `path/to/main/file.py` (N lines)
**Status:** [Preflighted / Tested / Production-tested]
**Reviewed by:** [Persona Name] ([Role])
**User concerns addressed:** [List from interview]

---

## Why Previous Versions Failed

### Failure 1: [Short Title]
**What we did:** [Factual description of the approach]
**Why it failed:** [Root cause, not symptoms]

### Failure N: ...

---

## What v[N] Changes

### Change 1: [Short Title] (lines X-Y)

[Description of the change with code snippets]

**What this fixes:** [Which failure mode from above]
**What could still go wrong:** [Honest risk — REQUIRED, cannot be empty]
**Honest risk level:** LOW / MEDIUM / HIGH — [justification]

### Change N: ...

---

## Expert Commentary

**[Persona Name]** — [Role/Title]

> **What I'm satisfied with:**
> - [From Phase 1b consultation]
>
> **What concerns me:**
> - [From Phase 1b consultation]
>
> **What I'd watch for in the first hour:**
> - [From Phase 1b consultation]

---

## Data Flow Diagram

[Use /create-figure with Mermaid backend to generate a flowchart]

```mermaid
flowchart TD
    A[Step 1] --> B[Step 2]
    B --> C{Decision}
    C -->|Yes| D[Path A]
    C -->|No| E[Path B]

Risk Matrix

[Use markdown table — /create-table if PDF output needed]

Remaining Risks (Honest Assessment)

Risk 1: [Title] (SEVERITY)

[Description, mitigation, what would actually fix it]

What Success Looks Like

How to Launch / Monitor / Kill

[Exact commands — copy-pasteable]

Bottom Line

Will it work? [Honest one-paragraph assessment] What's genuinely different this time? [Numbered list] What's the same? [What DIDN'T change — often reveals the real bottleneck]

### Phase 4: Claim Verification (CRITICAL)

Before presenting the walkthrough to the user, run the claim verification engine:

```bash
./run.sh verify --file path/to/walkthrough.md

The verifier extracts and checks:

For each claim, the verifier outputs:

VERIFIED  : src/foo.py exists (3,412 lines — MISMATCH: walkthrough says 3,337)
VERIFIED  : assess_qra() found at line 275
UNVERIFIED: "sentence_transformers not installed" — found in pi-mono embedding service
VERIFIED  : EMBEDDING_PORT default is 8602 (embed.py:33)
SKIPPED   : "4,017 controls" — requires database access (mark for manual check)

Rules:

• Every UNVERIFIED or MISMATCH claim must be fixed before presenting to user
• SKIPPED claims are flagged for user attention
• The agent MUST NOT present a walkthrough with known-false claims

Phase 5: Generate Visual Assets

Use /create-figure for:

• Data flow diagrams — flowchart TD in Mermaid (regenerable, diff-friendly)
• Architecture diagrams — system boundaries and integration points
• Workflow diagrams — multi-step processes with decision points

Use /create-table (or markdown tables) for:

• Risk matrices — change vs risk vs observable failure
• Success metrics — healthy/warning/sick thresholds
• Comparison tables — old approach vs new approach
• Failure history — what failed, why, root cause

Prefer Mermaid over ASCII art — it survives edits when the implementation changes.

Phase 6: Present for Review

Present the complete walkthrough to the user. The goal is adversarial review:

• The user reads it looking for claims they disagree with
• The user identifies risks the agent missed
• The user catches assumptions that don't match their operational experience
• The user validates the persona's commentary against their own knowledge

This is the highest-value step. The walkthrough is a collaboration surface, not a finished document.

Commands

verify — Claim Verification

# Verify all claims in a walkthrough
./run.sh verify --file walkthrough.md

# Show extracted claims without verifying
./run.sh verify --file walkthrough.md --extract-only

# Verify with verbose output (show check details)
./run.sh verify --file walkthrough.md --verbose

# Output as JSON (for CI/automation)
./run.sh verify --file walkthrough.md --json

template — Generate Blank Template

# Generate walkthrough template for a file
./run.sh template --file src/pipeline.py --output walkthrough.md

# Include git history for failure analysis
./run.sh template --file src/pipeline.py --include-git --output walkthrough.md

Integration with Other Skills

Anti-Patterns

Do NOT:

• Skip the interview — "I have deep context" is not an excuse. ASK THE HUMAN.
• Skip persona consultation — "No persona is relevant" is never true. Pick one.
• Write a monologue — If the walkthrough doesn't include user concerns + persona commentary, it's a monologue, not a collaboration.
• Write a walkthrough for something that has never been attempted (use /plan)
• Skip the "What could still go wrong" section (the whole point)
• Present unverified claims (run verify first)
• Use ASCII art for diagrams (use Mermaid — it survives edits)
• Make the walkthrough longer than the code it describes
• Hide failures or downplay risks (the user WILL find them)

The #1 Anti-Pattern: Agent Monologue

WHAT HAPPENED: Agent implemented code, then wrote walkthrough explaining
  its own work without asking the human or consulting a persona.
WHY IT'S BAD: The walkthrough only covers what the agent thinks matters.
  The human's actual concerns are invisible. The persona's domain
  expertise is absent. Bugs that the agent can't see go undetected.
HOW TO PREVENT: The Pre-Flight Checklist (above) blocks writing until
  both interview and persona consultation are complete.

The Walkthrough Is NOT:

• A CONTEXT.md (that's for agent handoff, not human review)
• A README (that's for onboarding, not for launch review)
• A plan (that's for what to do, not why this should work)
• Documentation (it's ephemeral — useful for one launch, then stale)

Example: When Walkthrough Caught Bugs

Bug 1: False Dependency Claim

WALKTHROUGH SAID: "sentence_transformers not installed in memory venv"
REALITY: Embedding service at pi-mono/.pi/skills/embedding/ uses sentence-transformers
USER CAUGHT: "isn't it in pyproject.toml and don't we use a service for embeddings?"
FIX: Updated walkthrough + corrected agent's mental model

Bug 2: Missing Semantic Check

WALKTHROUGH SAID: "assess_qra() covers quality gating" (with honest risk note)
USER CAUGHT: "shouldn't Brandon do probabilistic sampling for useless answers?"
FIX: Added run_semantic_sample() — a whole new feature

Bug 3: Missed Feature Opportunity (2026-02-13)

WALKTHROUGH SAID: Nothing about conversation prediction
REALITY: User wanted to know if episodic-archiver should predict next user request
USER CAUGHT: "should our episodic archiver use a /create-classifier to predict
  what the user will request next?"
ROOT CAUSE: Agent skipped interview, never asked what user cared about
FIX: Made interview + persona consultation MANDATORY in this skill

All three bugs were caught because the walkthrough process (when followed correctly) forces the human into the loop. Bug 3 was caught DESPITE the process being broken — the user caught it anyway. The fix is to prevent skipping.

Workflow Summary

flowchart TD
    START["/create-walkthrough triggered"] --> PF["Pre-Flight Checklist"]
    PF --> IV{"Phase 1: Interview\n(MANDATORY)"}
    IV -->|Not done| ASK["Use /interview or\nAskUserQuestion"]
    ASK --> IV
    IV -->|Done| PC{"Phase 1b: Persona\n(MANDATORY)"}
    PC -->|Not done| CONSULT["Use /ask consult <persona>"]
    CONSULT --> PC
    PC -->|Done| MEM["Memory recall +\ngit log + CONTEXT.md"]
    MEM --> ANALYZE["Phase 2: Read code,\nanalyze changes"]
    ANALYZE --> WRITE["Phase 3: Write walkthrough\n(incorporates interview +\npersona + memory)"]
    WRITE --> VERIFY["Phase 4: Claim verification\n./run.sh verify"]
    VERIFY -->|Mismatches| FIX["Fix claims"] --> VERIFY
    VERIFY -->|Clean| VISUAL["Phase 5: Diagrams + tables"]
    VISUAL --> PRESENT["Phase 6: Present for\nadversarial human review"]

Memory + Taxonomy Integration

Walkthrough findings are stored in /memory with /taxonomy bridge tags for recall, versioning, and drift detection across sessions.

How It Works

Pre-hook (recall): Before writing a new walkthrough, recall prior walkthrough findings for the same system to surface past failures, risks, and lessons.

Post-hook (learn): After successful claim verification, learn to memory:

1. Walkthrough summary — system, date, verdict, bottom line
2. Individual risks — for future recall
3. Verification stats — for drift tracking (accuracy trending over time)

All entries are tagged with taxonomy bridge attributes (Precision, Resilience, Fragility, etc.) extracted from the walkthrough content.

CLI Commands

# Learn walkthrough findings to memory after verification
./run.sh learn --file walkthrough.md --system "episodic-archiver" --bottom-line "Should work"

# Recall prior walkthroughs for a system
./run.sh recall "episodic-archiver"

# Recall with more results
./run.sh recall "episodic-archiver" -k 10

Graceful Degradation

Memory and taxonomy are optional. If unavailable:

• learn command exits with error message
• recall command exits with error message
• Core verify/template commands work normally without memory

File Structure

.pi/skills/create-walkthrough/
├── SKILL.md                            # This file (agent instructions)
├── walkthrough.py                      # Claim extraction + CLI (typer)
├── memory_integration.py              # Memory + taxonomy hooks
├── models.py                           # Shared data classes (Claim, Verdict, VerificationReport)
├── verifiers.py                        # All claim verifiers (13 types)
├── run.sh                              # Entry point
├── sanity.sh                           # Basic validation
└── references/
    └── walkthrough_template.md         # Blank template with all sections