explain-project

What this skill does

<!-- ═══════════════════════════════════════════════════════════════════
  EXPLAIN PROJECT SKILL
  ═══════════════════════════════════════════════════════════════════

  PURPOSE:
  Generates a comprehensive technical overview document (.docx) for any
  software project, written for a brilliant non-CS reader. The document
  includes all accessibility annotations baked in from the start:
  sidebars, glossary, inline definitions, and optional images.

  TARGET READER:
  A top-quintile intelligence mechanical engineer who has never taken
  a CS class. Sharp, process-oriented, comfortable with measurements
  and thresholds. Understands quality gates and structured problem-solving.

  INPUT MODES:
  1. Local project directory path (e.g., "C:\Users\...\my-project")
  2. Public GitHub URL (e.g., "https://github.com/owner/repo")
     - Clones to temp, generates doc to ~/Downloads, cleans up

  OUTPUT:
  A styled Word document (.docx) following the CFA brand guidelines,
  with the document structure adapted to the project's complexity.

  COMPANION TOOLS:
  Paths below are defaults on the author's machine. Override via flags or environment variables.
  - CLI tool: C:\Users\Troy Davis\dev\tools\doc-builder
    (python -m doc_builder create --content content.json --output doc.docx)
  - Structure template: C:\Users\Troy Davis\dev\info\technical-document-structure-template.md
  - Style guide: C:\Users\Troy Davis\dev\info\CFA_Word_Style_Guide.md
  - Image style: C:\Users\Troy Davis\dev\info\clean-style-sanitized.json
  - Image learnings: C:\Users\Troy Davis\dev\info\gemini-image-generation-learnings.md

  HISTORY:
  Built and tested 2026-03-27. Tested on 4 projects:
  - cfa/pipeline (complex ML pipeline, 25 pages)
  - cfa/kb-analysis (complex analysis pipeline, 21 pages)
  - stratfield/community-mgt (Next.js enterprise app)
  - personal/open-brain (multi-container AI knowledge system)
  ═══════════════════════════════════════════════════════════════════ -->

# Explain Project

Generate a comprehensive technical overview document for a project, written for a brilliant reader who lacks computer science training.

**Target reader:** A top-quintile intelligence mechanical engineer. Sharp, process-oriented, comfortable with measurements and thresholds, experienced with quality systems and structured problem-solving. Has never taken a CS class.

**Output:** A styled Word document (.docx) with all accessibility annotations baked in — sidebars, glossary, inline definitions, footnotes, developer section labels, and optionally generated images.

## Inputs

<!-- ─── INPUT PARSING ───
  Accept either a local filesystem path or a GitHub URL.
  GitHub URLs are shallow-cloned to /tmp, analyzed, then cleaned up.
  Output for GitHub repos goes to ~/Downloads by default.
─── -->

One required argument (either a local path OR a GitHub URL):
1. **Project directory path** -- a local directory containing the codebase to document
2. **OR GitHub URL** -- a public repo URL (e.g., `https://github.com/owner/repo`). The skill will clone it to a temp directory, analyze it, and output the document to the user's Downloads folder.

Optional flags:
- `--style PATH` -- Path to a markdown style guide for Word formatting (default: `$DOC_STYLE_GUIDE` env var if set; author's default: `C:\Users\Troy Davis\dev\info\CFA_Word_Style_Guide.md`)
- `--style-json PATH` -- Path to image style JSON for Nano Banana Pro (default: `$IMAGE_STYLE_JSON` env var if set; author's default: `C:\Users\Troy Davis\dev\info\clean-style-sanitized.json`)
- `--generate-images` -- Generate diagrams via Google Gemini and insert them (default: OFF — costs money)
- `--update` -- Incremental update mode: reads the existing document, diffs the codebase against the last generation (via git log since the commit hash in the document's freshness metadata), generates only changed sections, and preserves the user's manual refinements to unchanged sections
- `--output PATH` -- Output file path (default: `{project-dir}/docs/{project-name}-overview.docx`, or `~/Downloads/{repo-name}-overview.docx` for GitHub URLs)

Parse from the user's message. If neither a path nor URL is provided, ask.

### Detecting Previous Documents

Before starting a fresh generation, check for existing documents matching `docs/*-overview*.docx` in the project directory. If found:
1. Read the existing document to understand what it covers
2. Check git log for changes since the document was last generated (use the freshness metadata commit hash if available, otherwise file modification date)
3. Offer the user a choice: **update** (incremental, preserves manual edits) vs **regenerate** (full fresh generation)

In `--update` mode:
- Parse the existing document's section structure
- Diff the codebase to identify what changed (new files, modified stages, config changes)
- Generate only the sections affected by codebase changes
- Preserve the user's manual refinements to unchanged sections
- Update the Document Freshness metadata block with current values

### Handling GitHub URLs

<!-- ─── GITHUB FLOW ───
  Shallow clone keeps it fast. Only public repos — no auth complexity.
  isolation: worktree provides automatic cleanup — no manual rm needed.
  explain-project is read-only, so worktree cleanup is always safe.
─── -->

When the input is a GitHub URL (contains `github.com`):

1. **Clone the repo** using worktree isolation:
   ```yaml
   isolation: worktree
   ```
   Use `git clone --depth 1 "{url}" .` inside the worktree. Worktree auto-cleanup replaces manual `/tmp` directory management — no explicit cleanup step needed.

2. **Set output path** to Downloads:
   ```
   C:\Users\Troy Davis\Downloads\{repo-name}-overview.docx
   ```

3. **Analyze and generate** using the same Phase 1-5 process as for local projects.

Note: Only public repos are supported (no authentication). For private repos, clone manually first and provide the local path. Worktree cleanup is automatic because this skill is read-only and makes no commits.

## Process

<!-- ═══════════════════════════════════════════════════════════════════
  PHASE 1: DEEP PROJECT ANALYSIS

  This is where we build the understanding that drives the document.
  Read broadly first, then deeply into the components that matter most.
  Use the Explore agent for broad sweeps, direct reads for specifics.
  ═══════════════════════════════════════════════════════════════════ -->

### Phase 1: Deep Project Analysis

<!-- ─── DISPATCH TO EXPLORE AGENT ───
  Phase 1 is pure read-only analysis — no writes, no side effects.
  Dispatch to an isolated Explore subagent for broad parallel reading.
  Dynamic context injection pre-loads git stats before the subagent sees the prompt.
─── -->

**Dispatch this entire phase to an isolated Explore subagent:**
```yaml
context: fork
agent: Explore
```

Inject project git context before analysis:
- Recent commits: `!`git log --oneline -20``
- Top contributors: `!`git shortlog -sn --no-merges | head -10``

The Explore subagent builds comprehensive understanding:

1. **Project identity:** Read README, CLAUDE.md, package.json/pyproject.toml, and top-level docs
2. **Architecture:** Map the directory structure, identify major components, entry points, and data flow
3. **Pipeline/stages:** Identify processing stages, their order, inputs/outputs, and dependencies
4. **Data models:** Read model definitions, schemas, configuration files
5. **Products/outputs:** What does the system produce? What consumes the output?
6. **Testing:** Test suite structure, coverage, evaluation approach
7. **Infrastructure:** What hardware/services does it depend on? How does it deploy?
8. **Technical vocabulary:** Catalog every CS/ML/domain term the project uses
9. **Runtime artifacts:** If the project produces output artifacts (reports, logs, dashboards, metrics files), read them. Look for:
   - Latest pipeline output in `output/` or similar directories (statistics, counts, timing)
   - Log files with timing data, cache hit rat