---
name: feature-walkthrough
description: >-
  Explain the full logic and process of the current branch end-to-end so someone
  with no prior knowledge of the task can understand, review, and reproduce it.
  Scopes the change from the branch diff, traces the flow across every layer it
  touches (frontend tool/hook/component, Java controller/service/endpoint, Python
  engine, config, i18n, tests), and produces a self-contained walkthrough document
  with Mermaid diagrams (sequence/flow/architecture), annotated file map with
  clickable references, before/after behavior, screenshots where a UI is involved,
  a "try it locally" section, and edge cases/risks. Use when asked for a feature or
  branch walkthrough, "explain what this branch does", a design/logic writeup, PR
  reviewer onboarding, or a hand-off doc. Pass --html to also emit a rendered HTML
  version; --no-screens to skip screenshots.
argument-hint: "[branch-or-area] [--html] [--no-screens]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# Feature / Branch Walkthrough

Turn the current branch into a walkthrough a newcomer can follow. Audience:
**someone who has never seen this task**. Explain the *why*, the *flow*, and *how to
try it* - not just a diff summary.

`$ARGUMENTS` may name a branch or area to focus on; default is the current branch
vs `main`. Flags: `--html` (also emit a rendered HTML twin), `--no-screens`.

## Process

### 1. Scope the change
- `git log --oneline main..HEAD` and `git diff --stat main...HEAD` for the shape.
- Read the PR description / commit messages for stated intent. Do **not** invent
  history or motivation that isn't evidenced (state current behavior in present tense).
- Classify touched files by layer:
  - **Frontend**: tools (`frontend/editor/src/core/components/tools/*` or `.../core/tools/*`),
    hooks (`core/hooks/tools/*`, `useToolOperation`), contexts, routes, i18n
    (`public/locales/en-US`).
  - **Java backend**: controllers (`.../controller/api/...`), services, models, config.
  - **Engine**: `engine/src/stirling/{agents,contracts,api,services}`.
  - **Config / build / docker / tests.**

### 2. Trace the flow end-to-end
Follow one real path from user action to result. For a typical PDF tool that's:
UI control → `useToolOperation` hook → `POST /api/v1/...` → Spring controller →
service (PDFBox / LibreOffice / engine call) → response → review panel → download.
Read the actual files so the narrative is true to the code, and collect the exact
file:line anchors you'll cite.

### 3. Draw the diagrams (Mermaid)
Pick what fits; usually 2-3 of:
- **Sequence diagram** - request/response across frontend → backend → engine.
- **Flowchart** - the core decision/branching logic of the feature.
- **Architecture/component** - new pieces and how they wire to existing ones.
- **State** - if the feature has modes/steps.
Keep nodes labeled in plain language. Validate the Mermaid parses before shipping.

### 4. Screenshots (unless --no-screens)
If a UI is involved, capture key states with the stubbed Playwright harness
(see the **ui-walkthrough** skill and `files-page-screenshots.spec.ts` for the
pattern) or, for before/after, capture `main` then the branch. Drop PNGs in
`walkthrough/<feature>/` and reference them from the doc. For backend-only
changes, show request/response examples (curl + JSON) instead.

### 5. Write the walkthrough
Create `walkthrough/<feature>/FEATURE-WALKTHROUGH.md` with:
1. **TL;DR** - what the branch does and who it's for, in 3-4 sentences.
2. **Problem & approach** - what wasn't possible before; the chosen solution.
3. **Architecture diagram** + 1-paragraph orientation.
4. **End-to-end flow** - the sequence diagram + a numbered walk of each step,
   each citing the real file (clickable `path:line`).
5. **Key files** - annotated map (path → one line on its role).
6. **Logic deep-dive** - the flowchart + prose for the non-obvious decisions.
7. **Behavior** - before vs after; screenshots or request/response examples.
8. **Try it locally** - exact steps (`task dev` / `task dev:all`, the route to
   open or the curl to run, any env like `DOCKER_ENABLE_SECURITY` or a test
   license key). Make it copy-pasteable.
9. **Edge cases, risks, follow-ups** - what's untested, known limits, gotchas.

Markdown is the primary deliverable - it renders with diagrams in GitHub PRs and
IDEs, no build step, ideal for review.

### 6. If `--html`
Also emit `walkthrough/<feature>/walkthrough.html`: the same content with Mermaid
rendered via `mermaid.initialize({startOnLoad:true})` (script from CDN; note in
the file that rendering diagrams needs network, the `.md` is the offline copy) and
screenshots inline. Keep it self-contained otherwise.

### 7. Deliver
Give the doc path and a short chat summary. Offer to `SendUserFile` it.

## Principles
- **True to the code.** Every claim traces to a file you read; cite `path:line`.
  No fabricated migration/version history.
- **Newcomer-first.** Define repo-specific terms (FileContext, `useToolOperation`,
  the `@app/*` layer cascade, stubbed vs live tests) on first use.
- **Show, don't assert.** Prefer a diagram + a real example over adjectives.
- Don't commit the `walkthrough/` output unless asked.