project-recap

Load the visual-explainer skill and read cards/project-recap.md, then generate a comprehensive visual project recap as a self-contained HTML page.

Authoring contract. Prefer the MDX/React pipeline after the project-history and architecture fact-gathering checkpoint. Write the editable recap as .mdx by default, or .tsx when the recap needs custom interaction, generated SVG logic, or local state. Use shared components from visual-explainer-mdx/components.tsx, then export the generated standalone HTML with:

npm run ve:export -- <source.mdx> --out ~/.agent/diagrams/<slug>-project-recap.html

The generated HTML is the artifact, not the source of truth. Revise the MDX/TSX source when facts change or point-and-click feedback arrives, then re-export.

Clarify. This is a Tier 1 command per ./references/clarify.md. The time window usually comes from $1 (e.g., 2w, 30d, 3m) or defaults to 2w. If audience or depth is unclear (team onboarding vs. self-recall vs. leadership summary), ask 1 question. Bypass with --no-ask.

Follow the visual-explainer skill workflow. Read the reference template, CSS patterns, and mermaid theming references before generating. Use a warm editorial or paper/ink aesthetic with muted blues and greens, but vary fonts and palette from previous diagrams.

Time window — determine the recency window from $1:

• Shorthand like 2w, 30d, 3m: parse to git's --since format (2w → "2 weeks ago", 30d → "30 days ago", 3m → "3 months ago")
• If $1 doesn't match a time pattern, treat it as free-form context and use the default window
• No argument: default to 2w (2 weeks)

Data gathering phase — run these first to understand the project:

1. Project identity. Read README.md, CHANGELOG.md, package.json / Cargo.toml / pyproject.toml / go.mod for name, description, version, dependencies. Read the top-level file structure.

2. Recent activity. git log --oneline --since=<window> for commit history. git log --stat --since=<window> for file-level change scope. git shortlog -sn --since=<window> for contributor activity. Identify which areas of the codebase were most active.

3. Current state. Check for uncommitted changes (git status). Check for stale branches (git branch --no-merged). Look for TODO/FIXME comments in recently changed files. Read progress docs if they exist (~/.agent/memory/{project}/progress.md, ~/.pi/agent/memory/{project}/progress.md, .pi/todos/, or similar).

4. Decision context. Read recent commit messages for rationale. If running in the same session as recent work, mine the conversation history. Read any plan docs, RFCs, or ADRs in the project directory.

5. Architecture scan. Read key source files to understand the module structure and dependencies. Focus on entry points, public API surface, and the files most frequently changed in the time window.

Verification checkpoint — before generating HTML, produce a structured fact sheet of every claim you will present in the recap:

• Every quantitative figure: commit counts, file counts, line counts, branch counts
• Every module, function, and type name you will reference
• Every behavior and architecture description
• For each, cite the source: the git command output that produced it, or the file:line where you read it Verify each claim against the code. If something cannot be verified, mark it as uncertain rather than stating it as fact. This fact sheet is your source of truth during HTML generation — do not deviate from it.

Optional hero image — if surf CLI is available (which surf), generate a hero banner via surf gemini --generate-image --aspect-ratio 16:9 that visually captures the project's identity or domain. Match the style to the page's palette. Embed as base64 data URI using the .hero-img-wrap pattern from css-patterns.md. Place above or just below the title. Skip if surf isn't available — the page should stand on its own.