---
name: fp-ask
description: Answer a question grounded in fastpace domain context. Walks this repo's context first; on /fp-ask --org or when the answer is clearly cross-cutting, also consults the registered org repos via the cross-repo Q&A path. Always cite the source file. Read-only — never modifies anything. Triggers on /fp-ask <question>.
---

# fp-ask

Answer questions about **this repo** — and, when the question is org-wide, also about the **registered org repos**. Never speculate; every factual claim must be traceable to a specific file (or you say so explicitly).

This skill is the extension of `/fp-search` from per-repo to org-scope. The per-repo flow is the default; the cross-repo flow is opt-in via `--org` or kicks in automatically when the question clearly spans repos (e.g. "how does our billing flow work" when the current repo doesn't contain billing code).

## Scope decision (do this first)

1. If the user explicitly passes `--org`, `--cross-repo`, or `--all-repos` → **org scope**.
2. If the question contains words like "across our repos", "fleet-wide", "any repo", "our org" → **org scope**.
3. Otherwise → **this-repo scope** (the original behaviour below).

When in org scope:

- The list of registered org repos lives at `fastpace.org-repos.json` (repo root) or `.fastpace/org-repos.json`. Format: `{ "repos": [{ "name": "billing", "path": "/abs/path/billing" }, …] }`. If neither file exists, auto-discover sibling directories of cwd that contain a `fastpace/` directory.
- For each repo, look at the same context hierarchy as below (in that repo's tree). Identify which one or two repos are likeliest to hold the answer based on a cheap keyword pre-pass with Grep; only then read full files.
- The CLI command `fastpace ask "<question>"` does a deterministic keyword search across these registered repos and is the right tool for batch scripting; you should call it as a Bash tool if you need to seed a quick candidate list.

## Source hierarchy — this-repo flow (stop at first sufficient answer)

Walk these in order. Stop as soon as you have a grounded answer:

1. `fastpace/context/decisions.md` — the most authoritative. If a decision answers it, that's the answer.
2. `fastpace/docs/adr/*.md` — formal ADRs with full rationale.
3. `fastpace/context/architecture.md` — structure and data flow.
4. `fastpace/context/patterns.md` — if the question is "how do we usually do X?"
5. `fastpace/context/conventions.md` — naming, style, commit format.
6. `fastpace/context/glossary.md` — if the question is "what is X?"
7. `fastpace/context/learnings.md` — post-incident wisdom. **Filter to `status: reviewed` entries by default** (see below). Each entry is preceded by an `<!-- fp-entry · status: ... -->` comment.
8. `fastpace/context/team-learnings/*.md` — peer learnings pulled in by `fastpace learnings-sync`. Treat these as `reviewed` (they were reviewed in the originating repo before being shared). Cite by `[team] <author>-<date>`.
9. `fastpace/docs/prd/*.md` + `fastpace/docs/erd/*.md` — feature-scoped facts.
10. **Only then** grep the code — prefer Grep over wide reads. Never read node_modules or dist.

If none of the above hold the answer, say so explicitly — don't guess.

## Source hierarchy — org-scope flow

In org scope you walk the same hierarchy *per registered repo*. To stay cheap:

1. Run `fastpace ask --json "<question>"` first. It returns a ranked list of `{repo, file, score, hits}` matches. Use that to pick the 1–2 candidate repos.
2. In each candidate repo, read the matching context file(s) at the lines surfaced by the CLI before reading anything else.
3. Cite the repo name explicitly in every claim: `[billing/fastpace/context/decisions.md § 2026-03-04]`.
4. If multiple repos give different answers, surface the contradiction; do not collapse it silently.

## Process

1. Parse the user's question literally. If it's ambiguous ("why is it slow?"), ask one clarifying question before searching.
2. Decide scope (see above).
3. Walk the appropriate hierarchy. Use Grep with targeted terms first.
4. When you find a grounded answer, answer in ≤ 3 sentences. Cite the file (and the repo, in org scope).
5. If context is thin, offer `/fp-remember` or `/fp-teach` to capture the missing knowledge.

## Citation format

Every factual claim must carry a citation. Format:

```
Postgres was chosen over DynamoDB for transactional JSON queries across tenants
[fastpace/context/decisions.md § 2025-02-14].
```

Or for org scope:

```
The billing API uses idempotency-keys keyed by request_id
[billing/fastpace/context/patterns.md § 2026-02-10].
```

Or for ADRs:

```
See ADR 0007 — Use Postgres over DynamoDB
[fastpace/docs/adr/0007-use-postgres-over-dynamo.md].
```

Or for code (last resort):

```
Validation happens in `src/handlers/checkout.ts:42` (the `validateCard` call before submit).
```

## Answer shapes

| Question shape | Preferred answer shape |
|---|---|
| "Why did we choose X?" | Cite decision or ADR. If not captured, say so + offer `/fp-remember`. |
| "What is a Y?" | Quote glossary. If missing, offer to define it with `/fp-remember`. |
| "How do we handle Z?" | Cite patterns.md. If not a codified pattern, cite code and suggest `/fp-remember` for the pattern. |
| "Where does the X flow go?" | Cite architecture.md narrative + specific files. |
| "What's the status of feature F?" | Read watch card + PRD + ERD; summarize in one block. |
| "Has this been considered before?" | Grep `decisions.md` and ADRs for related terms; report what you find or confirm no prior record. |
| "How does our X work across repos?" | Org scope. Identify owning repo(s) from the registry; cite by repo. |

## Learnings — reviewed vs. unreviewed

`learnings.md` holds two kinds of entries distinguished by the HTML comment above each `## …` heading:

- `<!-- fp-entry · status: reviewed · … -->` — a human confirmed this. **Citable.**
- `<!-- fp-entry · status: unreviewed · … -->` — auto-captured by `/fp-extract-learnings`, not yet approved. **Do NOT cite as authoritative.**
- Entries with no comment — legacy (written before this system). Treat as `reviewed`.

**By default, filter out `unreviewed` entries** when answering. If the user explicitly asks to include unreviewed (e.g. "include unreviewed learnings" or passes `--include-unreviewed`), include them but mark each citation with `(unreviewed)` in the output so the reader knows.

`team-learnings/*.md` files (synced from other repos via `fastpace learnings-sync`) are pre-reviewed at the source and treated as citable; mark them `(team)` in citations.

## Failure modes to avoid

- **Don't speculate.** "I think it's because…" is forbidden. Either cite or say "this isn't captured anywhere."
- **Don't paraphrase context inaccurately.** Quote the exact line when precision matters.
- **Don't grep the whole repo.** Prefer targeted Grep with specific terms.
- **Don't grep every org repo eagerly.** Use the `fastpace ask --json` pre-pass to narrow first.
- **Don't read node_modules, dist, build, .next, .cache, coverage.**
- **Don't modify anything.** No `Edit`, no `Write`. Answer-only.
- **Don't dump a wall of text.** ≤ 3 sentences unless the user asks to go deep.

## When to escalate

- If you find the answer contradicts a recent decision → point out the conflict explicitly.
- If you repeatedly can't find something that *should* be captured → recommend `/fp-teach <topic>` to fix the gap for next time.
- If the question is really a design question → suggest `/fp-write-erd` instead of an ask.

## Exit criteria

- ≤ 3-sentence answer.
- At least one file citation (with repo name in org scope), or an explicit "this isn't captured anywhere" statement.
- Zero files modified.