fg-ask

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead.

Domain awareness

During codebase exploration, also look for existing documentation:

File structure

Most repos have a single context:

/
├── .forge/
│   ├── CONTEXT.md
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts. The map points to where each one lives:

/
├── CONTEXT-MAP.md
├── .forge/
│   └── adr/                          ← all ADRs live here (single location, every context)
├── src/
│   ├── ordering/
│   │   └── CONTEXT.md                ← glossary stays next to its code
│   └── billing/
│       └── CONTEXT.md

Create files lazily — only when you have something to write. If no .forge/CONTEXT.md exists, create one when the first term is resolved. If no .forge/adr/ exists, create it when the first ADR is needed.

During the session

Challenge against the glossary

When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

Update CONTEXT.md inline

When a term is resolved, update CONTEXT.md right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.

CONTEXT.md should be totally devoid of implementation details. Do not treat CONTEXT.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.

Offer ADRs sparingly

Only offer to create an ADR when all three are true:

1. Hard to reverse — the cost of changing your mind later is meaningful
2. Surprising without context — a future reader will wonder "why did they do it this way?"
3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in ADR-FORMAT.md.

---

Forge integration (minimal)

The original text ends above. What follows is the minimal glue that keeps the forge loop unbroken; the grilling method itself follows the original text above.

• Language: This skill file is authored in English, but you MUST write every message shown to the user — grilling questions, menus, status/next-step lines, and handoff text — in the user's language (detect it from the user's own messages), never mirroring this file's English. All documents this skill generates for the user's project (plan, run notes, retros, CONTEXT.md entries, ADRs, handoff messages) are written in the user's language. Section headings defined in the format docs are canonical English names — when writing a document, render headings in the user's language; consumers match sections by meaning and position, not exact strings.
• Forge root: every .forge/... path in this section is relative to the resolved forge root — .forge/ on the default branch, .forge/branch/<branch>/ (git-tracked) on any other branch. Resolve it per ${CLAUDE_PLUGIN_ROOT}/skills/fg-run/FORGE-ROOT.md (skill-relative ../fg-run/FORGE-ROOT.md) before reading or writing state — backlog, plan, CONTEXT.md, ADRs, and retros all live under that root. Two global exemptions stay at the top-level .forge/ regardless of branch: .forge/config.json (the tdd read below) and .forge/codebase/ (the map read below) — read both globally, never under the branch root (ADR-0011). Reads of the permanent fuel (CONTEXT.md, adr/, retro/) on a non-default branch overlay the branch root on top of the top-level .forge/ base — read both, branch wins on conflict; writes go to the branch root only (see FORGE-ROOT.md's read overlay).
• Before starting: feed back the latest retros. If .forge/retro/ exists, read it as a starting point for grilling — pull each retro's "Do differently next time" and "Divergences" into your opening questions (which past traps could recur this time, which assumptions broke). Selection rule (when retros have piled up): first take those in the same area as this task (overlapping slug stem / domain terms), then up to the most recent 3–5. Don't read all of them. Retros are reference fuel for sharpening the plan, not a source of truth — the plan's source of truth comes only from CONTEXT.md and ADRs. Read the active adr/*.md files (per the read overlay above — the top-level base plus the branch root on a non-default branch) as that ADR source of truth; do NOT read adr/retired/ at either level — those are ADRs the fg-cleanup utility retired (superseded/no-longer-applies, ADR-0012), kept on disk for archaeology but deliberately out of the active grilling fuel (retired numbers still count for numbering — see ADR-FORMAT.md). If there are no retros or none are relevant, skip silently.
• Before starting: read the codebase map. If .forge/codebase/ exists (produced by the fg-map utility), read the documents relevant to this task before grilling — they are a structured map of the stack, architecture, conventions, and known concerns, so you grill against the map instead of re-exploring the whole codebase from scratch (this is what cuts context rot). Check each document's last_mapped_commit frontmatter against the current HEAD (git rev-parse HEAD): if the map is many commits behind (e.g. dozens), warn in one line — "the codebase map is stale (mapped at {sha}, now {n} commits back); consider re-running fg-map" — then proceed anyway (do not block). If .forge/codebase/ does not exist, skip silently; the map is optional fuel, not a prerequisite.
• During grilling (conditional): external research as reference fuel. If the plan hinges on knowledge that is not in this repo — an unfamiliar library/framework, an external API/protocol/standard, or a domain the team lacks — or the user asks for it, you may gather grounding with a deep-research capability if one is available (e.g. a deep-research skill, or Claude's web research). This is optional fuel, not a prerequisite (same standing as .forge/codebase/): if no such capability exists, skip silently and grill with the project docs + codebase as usual — never hard-depend on a specific external skill. Never auto-run it — research is slow and costly, so offer first ("this looks like it needs external research on X — run deep research before we grill?") and run only on agreement. It does not replace grilling: findings are reference fuel, the one-question-at-a-time conversational grilling still happens, and the web is a reference — the source of truth stays CONTEXT.md/ADRs, not the research. Fold conclusions into the plan (Source of truth / decisions); if the research drives a hard-to-reverse technology choice, record it as an ADR under the usual gate. Do not dump raw research into a new doc. (See .forge/adr/0006-fg-ask-optional-deep-research-fuel.md.)
• Before starting: confirm TDD mode for this task. Read tdd from .forge/config.json (treat as off if the file doesn't exist — e.g. fg-tdd not set up). Use it as the default and ask once, early in grilling: "build this task test-first (TDD)? (default: )". The user's answer (or the default if they don't care) is recorded on the plan as <!-- tdd: on|off --> at Output time — fg-run reads it to run test-first when on. This sets execution mode only; it does not change how grilling itself is conducted.
• Before starting: check for existing work. Do this cheap state glance first — before the retro-feedback and codebase-map reads above — so grilling starts fast and no expensive setup is wasted if the user bails to finish prior work.
  • (1) Unfinished prior loop? (one quick, conditional prompt.) If the active slot has a run.md whose STATUS.md reads status: executed but is not yet sealed, or any .forge/executed/*/STATUS.md reads status: executed (a parked task awaiting retro), the previous loop's verification/retro/seal is unfinished — easy to forget once the work felt done. Surface it in one line and ask (in the user's language): "⚠ the previous task <slug> is awaiting [verification / retro / sealing] — (a) finish it first, or (b) keep starting the new task?" (several parked → just give the count). On (a), invoke fg-next — it derives whether verification, retro, or seal is owed via fg-status's state machine, so do not reimplement that decision here — and do not start the new grilling now (the user re-triggers fg-ask after finishing). On (b), proceed below — the new plan stacks in the backlog and coexists, exactly as designed. If there is no such unfinished work, say nothing and proceed immediately — the common case, zero added latency. Note: an active slot with only plan.md and no run.md (a promoted-but-unrun plan, awaiting fg-run) does not trigger this — it is not a retro/seal debt and coexists normally; warning on it would just be noise for deliberate backlog stacking.
  • (1b) Halted goal loop? If .forge/loop.md exists, an fg-loop drive is in flight or halted at a wall. Warn in one line: "⚠ a goal loop is halted at a wall () — (a) resume it via fg-loop, or (b) keep starting the new task? (a new plan is loaded as a non-member of the loop)". On (b) proceed normally — the new plan is safe from the unattended drive because fg-loop promotes only the slugs listed in loop.md's ## Tasks membership section (see ../fg-loop/SKILL.md §2); do not add the new plan to that list.
  • (2) Refine a pending plan vs. new task (and slug collision). Glance at the active slot (.forge/plan.md) and the backlog (.forge/backlog/) for an existing plan, and consult .forge/done/*/STATUS.md for what is already sealed. Resolve two things:
    • Already-sealed slug. If the requested work matches an already-completed slug, surface it ("a task with this slug was sealed on {date}") so the user knowingly starts a new cycle, and pick a non-colliding slug for the new plan.
    • A pending plan exists (in the backlog, or the active slot with no run.md — the "between fg-ask and fg-run" window where a requirement can still be added before execution). Be deterministic, not guess-based: name the pending plan(s) and ask in one line whether this request refines one of them or is a new task (list them if several). Ask only when a pending plan actually exists — say nothing on empty state (no noise on a fresh start). This removes the old ambiguity where re-invoking fg-ask would fold-or-fork at random.
      • On refine, still grill the addition (pillar #1 — never an un-grilled append), then recommend one of three by the addition's fit and size (the user decides — this reuses PLAN-FORMAT.md's splitting rule, which applies at refine time too, not only at first grilling):
        1. Entirely different concern (not part of the plan's goal) → recommend a separate new backlog plan (new slug + next monotonic task: number, no part: marker) that coexists — this is an independent task, not a split.
        2. Same concern, small & cohesive → fold into the plan: append slice(s) and update Goal / Non-goals / Source of truth, preserving its forge-slug / task: / tdd markers.
        3. Same concern but now large (decomposes into chunks each independently shippable, verifiable, sealable) → recommend a part-plan split (<base>-1ofM + <!-- part: N/M -->, per PLAN-FORMAT.md).
    • Boundary — never silently modify an active slot that already has a run.md. That plan has already run; editing it would pollute fg-learn's "Plan vs actual" comparison. A requirement on already-run work is a new task or a post-failure re-grill, not an in-place edit — confirm explicitly before touching it. If it is plainly a new task, proceed as is — the new plan stacks in the backlog and coexists with existing work.
• Output. Once grilling reaches a shared understanding, write the agreed plan to .forge/backlog/<slug>.md (slug = kebab-case of the task title, -2 on collision; the directory is created lazily). Embed a <!-- forge-slug: <slug> --> comment on the plan's first line — a persistent identifier that lets retro and sealing pair up by the same slug even after the plan moves to the active slot. Also assign a stable task number and embed <!-- task: N --> next to it: scan the task: markers of every existing plan (in .forge/backlog/, the active slot, .forge/executed/, .forge/done/), take the maximum, add one (or 1 if none exist). This number is the task's identity for fg-status display and fg-run selection — it never changes once assigned (see PLAN-FORMAT.md). Numbering applies to formal loop tasks only, not the fg-quick lane. Also record the TDD choice from the start-of-grilling question as a <!-- tdd: on|off --> marker near the forge-slug line (default = tdd in .forge/config.json, off if absent); fg-run reads it to run test-first when on (see PLAN-FORMAT.md). The format follows the skeleton in PLAN-FORMAT.md (or ${CLAUDE_PLUGIN_ROOT}/skills/fg-run/PLAN-FORMAT.md) — sharpened terms → source-of-truth glossary, hard-to-reverse decisions → ADR links, agreed units of work → slices (+ observable completion criterion), things decided not to do this time → non-goals. Split a big task into several plans when either applies (see PLAN-FORMAT.md's splitting rule): (a) a point needs human confirmation midway — narrow the plan up to there and leave the rest as a separate backlog task; or (b) the agreed work is large and decomposes into chunks that are each independently shippable, verifiable, and sealable — write one part-plan per chunk rather than one giant plan. For a size split, give each part an ordered slug (<base>-1of3, <base>-2of3, …) and a <!-- part: N/M --> marker so fg-run shows them in order and completes them one at a time; each part must still stand as its own full loop (it is a soft order, not a hard dependency). If during grilling the task turns out trivial enough that a retro will likely have nothing to fold into the docs (a tiny, low-risk change), you may add a <!-- retro-hint: optional --> marker comment near the forge-slug line — a non-binding hint that lets fg-run lead with the "skip retro" option at its handoff. Omit it by default; the actual skip is fg-run's call, gated on the run's divergence. Likewise, if a task's importance relative to other backlog work is clear, you may add a <!-- priority: high|medium|low --> marker near the forge-slug line — fg-run sorts its selection menu (and the "Run all" order) by it (high → medium → low, no marker = medium). It only changes ordering, never auto-selects; omit it when unsure.
• Handoff. After arranging the plan in the backlog, first list the documents this grilling created or touched, by path, so the user can review them before running — always the backlog plan (.forge/backlog/<slug>.md), plus any .forge/CONTEXT.md entry updated and any .forge/adr/NNNN-* added this session (only those actually touched). Say it conversationally — e.g. "I wrote the plan to .forge/backlog/<slug>.md (and updated CONTEXT.md / added ADR-NNNN); open them to review before we run." Then state the next step and stop — do not ask "shall I run it now?" and do not auto-invoke fg-run; chaining into the next stage is fg-next's job (ADR-0015). Tell them: the plan is in the backlog, and fg-run will pick it up (a selection menu if several wait, with "Run all" at the end), promote it, and run it. Give the trigger — "forge run" / "계획 실행" / /forge:fg-run, or fg-next to proceed in one step. Do not ask whether the task is big enough for a Dynamic Workflow vs. handling it directly — that is fg-run's call via its own cost estimate, not a grilling question.
• Volatile state. On the default branch, the volatile loop files this skill writes (the backlog plan and active-slot state) are gitignored; the permanent docs it updates (CONTEXT.md, ADRs, retros) are git-tracked via the .gitignore whitelist, and a non-default branch root is tracked whole (see FORGE-ROOT.md / ADR-0011).