---
name: fp-why
description: "Why does this file / line exist?" Traces a file back to the PRD/ERD/ADR/pattern/plan that shaped it, plus git history (introducing commit + recent changes + optional line blame). Richer than `git blame`. Runs locally. Triggers on /fp-why <path>[:line].
---

# fp-why

Answer "why does this exist?" for a file (or a specific line). Returns a concise traceability report — which product artifact drove it, which decisions govern it, who touched it last.

## Preflight

- Verify the file exists in the repo. If not, say so and stop.
- Read `fastpace/context/architecture.md` once to understand the module map (useful for framing "this file lives in module X").

## Process

1. Prefer the CLI:
   ```
   fastpace why <path>        # or <path>:<line>
   ```
   Its output is already formatted; surface it verbatim.
2. Fallback (no CLI or empty output):
   - **PRDs / ERDs / ADRs / exec-plans** — grep `fastpace/docs/prd/`, `.../erd/`, `.../adr/`, `fastpace/exec-plans/` for the file path or basename.
   - **Architecture / decisions / patterns** — grep `fastpace/context/architecture.md`, `decisions.md`, `patterns.md` for the file's module name (first path segment) or basename.
   - **Git** — `git log --follow --reverse -- <path>` for the introducing commit; `git log -n 5 -- <path>` for recent; if a line was given, `git blame -L <n>,<n> -- <path>`.

## Output format

```
⚡ why src/handlers/checkout.ts:62

PRDs reference this
  fastpace/docs/prd/credit-card-validation.md  Credit card validation

ERDs reference this
  fastpace/docs/erd/credit-card-validation.md  Credit card validation — Engineering Requirements

Decisions touching the module
  fastpace/context/decisions.md:14  ## 2025-02-14 — No ORM in handlers

Patterns touching the module
  fastpace/context/patterns.md:22  ## retry-with-backoff

Git history
  introduced: 9c1a3f2 2025-02-10 priya · feat(checkout): wire card validator
  recent:     4d2e88a 2026-04-14 lee · fix: return 400 on expired cards
  blame L62:  a1b2c3d4 (priya 2025-02-10) await validateCard(req.body.card);
```

## Rules

- **Read-only.** Never modify files.
- **Cite everything.** Every claim carries a `path:line` or commit sha.
- **Scope the grep.** Use the file path + its module (first path segment) + the basename without extension. Don't scan the whole codebase.
- **If nothing lands**, say so clearly and suggest `/fp-remember` or `/fp-write-adr` to capture why this file exists.
- **Be terse.** 3-6 groups max, 5 lines per group.

## Integration

- If the file is clearly governed by one ADR or decision, call that out at the top of the response — it's often the answer by itself.
- If the user wanted behavior ("why does it do X?") instead of existence ("why is it here?"), redirect to `/fp-ask`.
- If the user wants the full trace into product/design docs, recommend opening `fastpace ui` → Docs view alongside.

## Exit criteria

- A short, sectioned trace (or a clear "nothing captured yet" message) printed.
- Zero files modified.