--- name: fp-remember description: Capture a piece of domain knowledge into the fastpace context so it survives across sessions and models. Classifies the input (decision / learning / term / pattern) and appends to the right file. For substantive decisions, suggests /fp-write-adr instead. Append-only for decisions and learnings. Triggers on /fp-remember . --- # fp-remember Make a thought durable. The user tells you something worth preserving; you classify it, check for duplication, format it correctly, and append to the right file in `fastpace/context/`. ## Preflight - Confirm `fastpace/context/` exists with foundation files. If not, suggest `/fp-discover` first and stop. - If the user's input is a vague feeling ("we should be more careful about X"), ask one question to pin it down: "What's the specific rule, or the specific incident?" ## Classification Every input lands in exactly one of four buckets. Ask *one* question if genuinely ambiguous — most aren't. | Bucket | Indicator phrases | File | |---|---|---| | **Decision** | "we chose", "we're using", "we decided", "going with", "picked" | `decisions.md` (append-only) | | **Learning** | "learned", "figured out", "got burned by", "turns out", "incident" | `learnings.md` (append-only) | | **Term** | "means", "is defined as", "our word for" | `glossary.md` (edit-friendly) | | **Pattern** | "the way we do", "we always", "standard idiom for" | `patterns.md` (edit-friendly) | ## Escalation to /fp-write-adr If the thing is a **decision** AND any of these are true, stop and suggest `/fp-write-adr` instead: - It crosses a module boundary or changes the data model. - The user is picking between libraries/frameworks with meaningful tradeoffs. - It will be hard or expensive to reverse. - Someone will later ask "why did we do this?" - It needs reviewers to cite it in PRs. Say: "This sounds substantive — `/fp-write-adr` will give it full rationale + consequences. Or want the short form here? (adr / short)". Default to the user's preference; don't force. ## Process 1. Parse the user's input. Identify the bucket. 2. **Check for duplicates.** Grep the target file for near-matches. If one exists: - For `glossary.md` / `patterns.md`: offer to update in place (show diff first). - For `decisions.md` / `learnings.md`: **never edit.** Append a new entry that supersedes, and say so in the new entry's text. 3. Resolve any relative dates to absolute ISO dates. "Last week" → `2026-04-17`. 4. Draft the entry using the exact format below. 5. Show the user the diff. On confirmation, append. 6. Report: file + section + git-add hint. ## Append formats (exact) ### `decisions.md` (append-only, ADR-lite) ```markdown ## — **Context:** **Decision:** **Consequences:** **Author:** ``` If superseding: the new entry's **Context** references the prior entry by date, and the new entry's title includes "(supersedes )". ### `learnings.md` (append-only) ```markdown ## — **Why it matters:** **Evidence:** ``` ### `glossary.md` (edit-friendly) ```markdown - **** — . Example: . Not to be confused with: . ``` New terms alphabetized within the file. ### `patterns.md` (edit-friendly) ```markdown ## **When:** **Don't use when:** **Shape:** ``` ``` **Used in:** ``` ## Rules - **Append-only means append-only.** For `decisions.md` and `learnings.md`, never overwrite or edit a prior entry. Add a new entry that explicitly supersedes. - **Be specific.** "We chose Postgres" is useless. "We chose Postgres over DynamoDB because we need transactional JSON queries across tenants" is useful. - **Absolute dates only.** Resolve every relative reference before writing. - **One entry per invocation.** If the user gives you three things, write three — but confirm each separately. - **Preserve the user's voice.** Quote when precision matters; don't sand it down to generic phrasing. - **Don't fabricate context.** If the user gave you a sparse input, ask one follow-up. Don't pad with guesses. - **Flag contradictions.** If the new decision contradicts an existing one, say so and either supersede (with explicit acknowledgment) or redirect to `/fp-write-adr`. ## Examples of good vs. bad **Bad learning:** "retry storms are bad" **Good learning:** ``` ## 2025-03-02 — Backing off without jitter caused a thundering herd When the payment service recovered from an outage, every client retried at the same base interval and immediately re-overloaded the service. **Why it matters:** Every retry loop must add jitter. Use `withRetry` (patterns.md) which bakes it in. **Evidence:** incident #142, fix in PR #2891 ``` **Bad decision:** "use Postgres" **Good decision:** ``` ## 2025-02-14 — Postgres over DynamoDB for primary store **Context:** Multi-tenant transactional writes over JSON-heavy rows. DynamoDB's eventual consistency on secondary indices broke our atomicity needs. **Decision:** Postgres 15 as primary; redis for session state only. **Consequences:** Ops cost higher; schema migrations now required; regained transactional guarantees we assumed. **Author:** priya ``` ## Integration - After writing a learning that's *tactical* ("the fix is X"), suggest: "Want the fix captured as a pattern too? `/fp-remember` with `patterns.md` target." - After writing a decision that's borderline-substantive, leave the door open: "If this gets questioned later, upgrade to an ADR with `/fp-write-adr`." - If the user is capturing many related learnings in a row, suggest `/fp-teach ` to structure them. ## Exit criteria - Exactly one file appended (with a user-confirmed diff). - Diff showed to user before writing. - Report: file + section heading + "run `git add ` to commit".