Feature Walkthrough

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.