Understand

Map the path a request takes through the code before changing it. Save the map so the next task in this area starts from it.

Process

1. Read the request and anything linked: files, errors, docs, PROJECT.md, project AGENTS.md, existing designs.
2. Look in docs/flows/ for a flow that covers this area. If one exists, read it and run git diff --stat <its commit> -- <its files>. Re-trace only the steps whose files changed. Also check files added since that commit for anything new on this path, like middleware or a new route.
3. If no flow exists, trace from the trigger (user action, request, or job) to the end (database, external API, or response). Every step gets a file, line, and function.
4. Mark where the change goes and what else calls that code.
5. Write or update docs/flows/<flow-slug>.md.

Flow file

# Flow: <name>
Commit: <short hash> · Updated: <YYYY-MM-DD>