---
name: fp-teach
description: Interactive teaching session where the user explains a subsystem, business rule, or convention and you distill it into append-only fastpace/context/ entries. Great for onboarding fastpace with knowledge /fp-discover can't infer from code alone. Triggers on /fp-teach [topic].
---

# fp-teach

Turn a conversation into durable, structured context. The user talks; you ask focused questions; you write clear, citable entries into `fastpace/context/`.

## When to use this vs /fp-remember

- `/fp-remember <one fact>` — user already knows what to capture, wants it written.
- `/fp-teach <topic>` — user wants to *explain* something bigger; you interview them, then write.

If the user's input is a single factoid ("we chose Postgres because…"), redirect to `/fp-remember` and stop.

## Preflight

- Confirm `fastpace/context/` exists with foundation files. If not, suggest `/fp-discover` first and stop. You can't teach without a baseline.
- If the user's topic is already well-covered (e.g. they want to teach you "the deploy process" but `architecture.md` has a detailed deploy section), *read it first* and start the interview from where it ends, not from scratch.

## Process

1. **Confirm the topic.** If the invocation had no topic, ask: "What area do you want me to learn? (domain term · subsystem · process · convention · pattern)". One sentence, one ask.
2. **Decide the target file** before asking anything:
   - Domain term → append to `glossary.md`
   - Subsystem/architecture → new section in `architecture.md`
   - Convention (naming, commits, PR flow) → `conventions.md`
   - Reusable code idiom → `patterns.md`
   - Decision with rationale → `decisions.md` (append-only; see `/fp-remember` format below)
   - Cross-cutting/multi-file → multiple writes, but confirm each one.
3. **Interview.** 5-10 questions total, **one at a time**. Adaptive — follow up on interesting answers, don't stick to a rigid script.
4. **Draft the entry** after you have enough. Show the user the exact text before writing.
5. **Confirm → write** — one file at a time, show the diff, wait for approval.
6. **Close with a summary**: which files were updated, which git command to review, and a suggestion for a follow-up teach session if there's a related gap.

## Question patterns by target

### For `glossary.md` (domain terms)
- "Say it in one sentence for a new hire."
- "When would someone use this term vs. a synonym?"
- "Is there a concrete example I can reference?"

### For `architecture.md` (a new subsystem)
- "What problem does this subsystem solve?"
- "Where does traffic enter and exit?"
- "What's the data store?"
- "What are the external dependencies?"
- "What's one failure mode that surprised the team?"

### For `conventions.md`
- "What's the rule, exactly?"
- "Why — what breaks when we don't follow it?"
- "Is there a lint rule enforcing it, or just convention?"

### For `patterns.md`
- "What code shape is this?"
- "What problem does it solve?"
- "Where is it used today?"
- "When NOT to use it?"

### For `decisions.md` (short ADR-lite)
- "What were you deciding between?"
- "Why the chosen option?"
- "What's the tradeoff you accepted?"
- *If substantive → suggest `/fp-write-adr` instead.*

## Output formats (exact)

### glossary.md — append a definition

```markdown
- **<term>** — <one-sentence definition>.
  Example: <concrete example>. Not to be confused with: <nearby term>.
```

### architecture.md — append a subsystem section

```markdown
## <Subsystem name>

**Purpose.** <1-2 sentences>

**Entry points.** <HTTP routes / queues / CLI commands>

**Data.** <tables / indices / cache layers>

**External dependencies.** <services, APIs>

**Failure modes.** <what breaks, what to watch>
```

### conventions.md — append a rule

```markdown
### <rule name>

- **Rule:** <what to do>
- **Why:** <what it prevents>
- **Enforced by:** <lint / hook / convention only>
```

### patterns.md — append a pattern

```markdown
## <pattern-name>

**When:** <situations>
**Don't use when:** <situations>
**Shape:**
```<lang>
<minimal representative snippet>
```
**Used in:** <file paths or "widespread">
```

### decisions.md — append-only ADR-lite

```markdown
## <YYYY-MM-DD> — <short title>
**Context:** <what prompted this>
**Decision:** <what we chose>
**Consequences:** <tradeoffs, implications>
**Author:** <user>
```

## Rules

- **Preserve the user's voice.** If they said "the thundering herd thing", put it in a quote — don't sand it down to "cascading request failures" unless they asked.
- **Absolute dates only.** "Last week" → `2026-04-18`. Never relative.
- **One question at a time.** No questionnaires. No "I'll ask you 8 quick things."
- **Don't overwrite.** If the user contradicts an existing entry, *append* a new entry that supersedes. For `decisions.md`/`learnings.md`, this is mandatory (they're append-only).
- **Don't fabricate examples.** If the user can't give you an example, note "example: TBD".
- **Don't teach in one file what belongs in another.** If they describe three things, write to three files.
- **Resist long sessions.** After ~10 questions, write what you have. The user can run `/fp-teach` again tomorrow.

## Integration

- After writing, suggest a follow-up: "Want to capture a related learning with `/fp-remember`?" or "This might deserve a full ADR — try `/fp-write-adr`."
- If the user taught you a brand-new subsystem, remind them: "Update `context.level` in `fastpace.config.yaml` if this raises your level."

## Exit criteria

- At least one context file updated with a user-confirmed diff.
- A ≤ 5-line summary printed: which files, which entries added, the git add command.