forge-orkes 0.3.9 → 0.3.10

package/template/.claude/skills/discussing/SKILL.md

@@ -1,105 +1,88 @@
 ---
 name: discussing
-description: "Use when you need to talk through approach, trade-offs, or concerns before committing to action. Trigger between researching and planning (pre-plan discussion), or invoke on any existing phase/plan to revisit decisions. This skill facilitates conversation — it doesn't write plans or code."
+description: "Talk through approach, trade-offs, or concerns before committing to action. Enters between researching and planning, or revisits existing plans on demand. Produces conversation and decisions — no plans, no code."
 ---
 
 # Discussing
 
-Facilitate a structured conversation about approach, trade-offs, and decisions. This skill produces clarity, not artifacts.
+Structured conversation about approach, trade-offs, and decisions. Produces clarity, not artifacts.
 
 ## When to Invoke
 
-### Pre-Planning (Default Position in Workflow)
-After `researching`, before `planning`. The agent has findings — now help the user decide what to do with them before locking anything into a plan.
+| Trigger | Context |
+|---------|---------|
+| Pre-planning | After `researching`, before `planning`. Research findings available — decide what to do with them. |
+| Post-planning | User says "discuss Phase 2" or "rethink the auth approach." Plan exists, user wants to revisit. |
+| Mid-workflow | User feels uncertain or says "wait," "what are the alternatives?" Available from any skill. |
 
-### Post-Planning (On-Demand)
-User says "discuss Phase 2" or "let's talk through plan 03" or "I want to rethink the auth approach." The plan exists but the user wants to revisit it before (or instead of) executing.
+## Boundaries
 
-### Mid-Workflow
-User feels uncertain, wants to step back, or says things like "wait," "I'm not sure about this," "what are the alternatives?" Route here from any skill — discussion is always available.
-
-## What This Skill Does NOT Do
-
-- **Does not write plans.** That's the `planning` skill.
-- **Does not write code.** That's the `executing` skill.
-- **Does not modify `.forge/` files.** Discussion produces decisions — the next skill writes them down.
-- **Does not require a phase or plan to exist.** You can discuss a vague idea.
-
-The only output is the conversation itself and, at the end, a summary of decisions made that the next skill should honor.
+- Does not write plans, code, or `.forge/` files.
+- Does not require a phase or plan to exist.
+- Only output: the conversation itself + a decision summary the next skill honors.
 
 ## Pre-Planning Discussion
 
-When entering from `researching` (potentially after a context clear):
-
 ### Step 0: Load Context
 
-If entering with a fresh context (after `/clear`):
+If entering with fresh context (after `/clear`):
 
 ```
 Read: .forge/state/milestone-{id}.yml → current position, progress
 Read: .forge/project.yml → tech stack, project description
-Read: .forge/context.md → any existing locked decisions (if exists)
+Read: .forge/context.md → existing locked decisions (if exists)
 Read: .forge/constitution.md → active gates (if exists)
 ```
 
-Check if research findings were written to files (`.forge/phases/` or similar). If so, read them. If research was inline-only (conversation context), the findings may need to be re-summarized from the user — ask briefly: *"We're picking up after the research phase. Can you summarize the key findings, or should I re-scan the relevant areas?"*
+Check for research findings in `.forge/phases/` or similar. If research was inline-only, ask: *"We're picking up after research. Summarize the key findings, or should I re-scan?"*
 
 ### Step 1: Present Decisions with AskUserQuestion
 
-Summarize what research found, structured around decisions the user needs to make — not a data dump.
+Summarize research structured around decisions — not a data dump.
 
-**Use the `AskUserQuestion` tool for every decision point.** This gives users a clean, scannable interface instead of walls of text. You can batch up to 4 questions per `AskUserQuestion` call.
+**Use `AskUserQuestion` for every decision point.** Batch up to 4 questions per call.
 
 For each decision:
-1. Write a **brief prose intro** (2-3 sentences max) setting context for the decision — what's the problem, why does it matter.
-2. Then immediately call `AskUserQuestion` with:
+1. Write a brief prose intro (2-3 sentences max) setting context.
+2. Call `AskUserQuestion` with:
    - `question`: The decision stated plainly, ending with `?`
-   - `header`: Short label (e.g., "Strategy", "Approach", "Scope")
-   - `options`: 2-4 realistic approaches. Each option gets:
-     - `label`: Concise name (1-5 words). Put your recommendation first with "(Recommended)" suffix.
-     - `description`: Trade-offs — what you gain and what you lose. Be honest about costs.
-   - `multiSelect`: false for mutually exclusive choices, true when combinations are valid.
+   - `header`: Short label (e.g., "Strategy", "Scope")
+   - `options`: 2-4 approaches. Each gets a `label` (1-5 words, recommendation first with "(Recommended)" suffix) and `description` (trade-offs — gains and costs).
+   - `multiSelect`: false for mutually exclusive, true when combinations are valid.
 
-**Batch related decisions.** If you have 3-5 decisions, group them into 1-2 `AskUserQuestion` calls (max 4 questions each) rather than asking one at a time. This lets the user see the full landscape and make coherent choices.
+**Batch related decisions** into 1-2 calls so the user sees the full landscape.
 
-**When NOT to use AskUserQuestion:** For open-ended exploration questions where the answer isn't one of a few discrete options (e.g., "Walk me through the ideal user flow"), use regular prose. The tool is for decisions with concrete choices, not brainstorming.
+**Skip AskUserQuestion for open-ended exploration** (e.g., "Walk me through the ideal user flow"). The tool is for decisions with discrete choices.
 
-Example structure for a discussion with 3 decisions:
+Example structure:
 
 ```
-Brief context paragraph explaining the landscape from research.
+Brief context paragraph from research.
 
 → AskUserQuestion with questions:
-  1. "Which recovery strategy should we use?" (header: "Recovery")
+  1. "Which recovery strategy?" (header: "Recovery")
      - "Sweep timer (Recommended)" / "Sweep timer + queue refactor" / ...
   2. "Where should observability live?" (header: "Observability")
      - "Server-side logs only" / "PostHog events" / "Both" / ...
-  3. "How should we handle the 704 contradictory records?" (header: "Data cleanup")
-     - "Migration + constraints" / "Let sweep handle it" / "Migration only" / ...
+  3. "How to handle the 704 contradictory records?" (header: "Data cleanup")
+     - "Migration + constraints" / "Let sweep handle it" / ...
 ```
 
-Surface the 3-5 decisions that actually matter. Don't present a 20-item matrix.
+Surface the 3-5 decisions that matter. Not a 20-item matrix.
 
 ### Step 2: Facilitate, Don't Dictate
 
-After the user responds to decisions, your role is to help them think deeper — not to push your preference.
-
-**Use `AskUserQuestion` for follow-up decisions** that emerge from their answers. Use prose for open-ended exploration.
-
-Good facilitation patterns:
-- *"The main tension here is between X and Y."* → then `AskUserQuestion` with the concrete options
-- Referencing earlier decisions: *"You chose Option A for recovery — that makes X a more natural fit for observability."* → then `AskUserQuestion` with refined options
-- When trade-offs need explicit weighing → `AskUserQuestion` with `description` fields that name the costs
+After the user responds, help them think deeper — don't push your preference. Use `AskUserQuestion` for follow-up decisions; prose for open-ended exploration.
 
-Bad facilitation patterns:
-- Presenting options as prose paragraphs when they could be `AskUserQuestion` choices
-- Asking "what do you think?" without giving the user something concrete to react to
-- Overwhelming with edge cases before the main path is clear
-- Treating every decision as equally important
+| Good | Bad |
+|------|-----|
+| Name the tension, then offer concrete options via AskUserQuestion | Present options as prose paragraphs |
+| Reference earlier decisions to refine later ones | Ask "what do you think?" without giving something to react to |
+| Use `description` fields to name costs | Overwhelm with edge cases before the main path is clear |
 
 ### Step 3: Probe for Hidden Constraints
 
-Research often misses things the user knows but hasn't mentioned. Use `AskUserQuestion` for structured probes where the answer shapes the plan:
+Research often misses what the user knows but hasn't mentioned. Use `AskUserQuestion` for structured probes:
 
 ```
 AskUserQuestion:
@@ -114,222 +97,198 @@ AskUserQuestion:
       description: "Do it right, scope is flexible"
 ```
 
-For open-ended probes where you need the user to explain (not choose), use prose:
-- *"Have you tried something similar before? What went wrong?"*
-- *"Anything you definitely want or definitely don't want?"*
+For open-ended probes, use prose:
+- *"Tried something similar before? What went wrong?"*
+- *"Anything you definitely want or don't want?"*
 
-One or two questions at a time. Don't interrogate.
+One or two questions at a time.
 
 ### Step 4: Functionality Distillation
 
-This is the heart of the discussing skill. Walk through each major feature or requirement and ask targeted questions that force clarity about *how the system should actually behave*. The goal is to surface the implicit assumptions and edge cases that the user hasn't articulated yet — but will need answers to during implementation.
+Walk through each major feature and ask targeted questions that force clarity about how the system behaves. Surface implicit assumptions and edge cases the user hasn't articulated.
 
-**For each feature/requirement, work through these question layers:**
+**Five question layers per feature/requirement:**
 
-**Layer 1: The Happy Path**
-What does success look like from the user's perspective? Walk through the ideal scenario step by step.
-- *"When a user [triggers this feature], what should they see/experience first?"*
-- *"Walk me through what happens next — what's the sequence?"*
-- *"When it's done, what confirms to the user that it worked?"*
+| Layer | Focus | When to use |
+|-------|-------|-------------|
+| 1. Happy Path | What success looks like step by step | Always |
+| 2. Boundaries & Rules | Permissions, limits, triggers, preconditions | Anything with rules |
+| 3. Failure Modes | Invalid input, service down, cancellation, concurrency | Critical paths (payments, data mutations, auth, integrations) |
+| 4. Interactions & Side Effects | Cascading updates, notifications, undo, related features | Features with shared state or dependencies |
+| 5. Evolution | v1 vs. final shape, scope cuts, likely future changes | Uncertain scope |
 
-**Layer 2: Boundaries and Rules**
-What are the constraints? What's allowed and what isn't?
-- *"Who can do this? Everyone, or only certain roles/states?"*
-- *"Is there a limit — how many, how often, how large?"*
-- *"What triggers this — user action, scheduled event, or reaction to something else?"*
-- *"Does this depend on anything else being true first?"*
+**Layer 1 — Happy Path:**
+- *"When a user triggers this, what do they see first?"*
+- *"What's the sequence?"*
+- *"What confirms it worked?"*
 
-**Layer 3: When Things Go Wrong**
-What happens when the expected path breaks?
-- *"What if [the input is invalid / the service is down / the user cancels halfway]?"*
-- *"Should the system retry, fail gracefully, or alert someone?"*
-- *"If two users do this simultaneously, what should happen?"*
-- *"What's the worst thing that could happen if this feature has a bug?"*
+**Layer 2 — Boundaries:**
+- *"Who can do this?"*
+- *"Any limits — how many, how often, how large?"*
+- *"What triggers it — user action, schedule, or reaction?"*
 
-**Layer 4: Interactions and Side Effects**
-How does this feature affect the rest of the system?
-- *"When this happens, does anything else need to update?"*
-- *"Should other users be notified? How?"*
-- *"Does this affect [related feature the research uncovered]? How?"*
-- *"Can this be undone? Should it be?"*
+**Layer 3 — Failures:**
+- *"What if the input is invalid / service is down / user cancels halfway?"*
+- *"Retry, fail gracefully, or alert?"*
+- *"What if two users do this simultaneously?"*
 
-**Layer 5: Evolution**
-How might this change over time?
-- *"Is this a v1 that you expect to expand later, or is this the final shape?"*
-- *"If you had to cut scope, which parts of this are essential vs. nice-to-have?"*
-- *"What's the most likely thing you'd want to change about this in 3 months?"*
+**Layer 4 — Side Effects:**
+- *"Does anything else need to update?"*
+- *"Should others be notified? How?"*
+- *"Can this be undone?"*
 
-**How to use the layers:**
+**Layer 5 — Evolution:**
+- *"v1 that expands later, or final shape?"*
+- *"If you cut scope, what's essential vs. nice-to-have?"*
 
-Don't mechanically walk through all 5 layers for every requirement — that would take hours. Instead:
+Don't mechanically walk all 5 layers for every requirement. Ask 2-3 questions at a time, go deeper where answers reveal uncertainty.
 
-- **Always do Layer 1** — if the happy path isn't clear, nothing else matters.
-- **Do Layer 2 for anything with rules** — permissions, limits, validations, workflows.
-- **Do Layer 3 for anything critical** — payments, data mutations, auth, external integrations.
-- **Do Layer 4 when features interact** — if research found shared state or dependencies between features.
-- **Do Layer 5 when scope feels uncertain** — if the user seems unsure how much to build now.
+Use `AskUserQuestion` for behavior decisions with discrete answers. Use prose when you need the user to describe or explain.
 
-Ask 2-3 questions at a time, let the user respond, then go deeper where their answers reveal uncertainty. The conversation should feel like a collaborative design session, not an interrogation.
-
-**Use `AskUserQuestion` for behavior decisions within distillation.** When a question has discrete answers (retry vs. fail vs. alert, real-time vs. polling, roles A/B/C), use the tool. When you need the user to describe or explain something open-ended, use prose.
-
-Example — Layer 3 question as `AskUserQuestion`:
+Example — Layer 3 as AskUserQuestion:
 ```
-question: "When the external enrichment API is down, what should the system do?"
+question: "When the enrichment API is down, what should the system do?"
 header: "Failure mode"
 options:
   - label: "Retry with backoff (Recommended)"
-    description: "Queue retries at 1m/5m/30m intervals. Adds complexity but self-heals."
+    description: "Queue retries at 1m/5m/30m. Adds complexity but self-heals."
   - label: "Fail and alert"
-    description: "Mark as failed, send alert. Simple but requires manual re-trigger."
+    description: "Mark failed, send alert. Simple but requires manual re-trigger."
   - label: "Skip and continue"
     description: "Process remaining items, revisit failures in next sweep."
 ```
 
-**What you're listening for:**
-
-- **Contradictions** — "It should be simple" but also "it needs to handle 12 different states." Surface these gently.
-- **Vague handwaving** — "It should just work normally." Push for specifics: *"What does 'normally' mean here? Can you describe one concrete example?"*
-- **Assumed knowledge** — "Like how Stripe does it." Confirm you share the same mental model: *"I want to make sure I understand — you mean [specific behavior], right?"*
-- **Energy shifts** — When the user gets excited about a detail, that's signal. When they get bored or dismissive, that's also signal. The things they care about should get more attention in the plan.
+**Listen for:**
+- **Contradictions** — "It should be simple" + "12 different states." Surface these.
+- **Vague handwaving** — "It should just work." Push: *"What does 'normally' mean here? One concrete example?"*
+- **Assumed knowledge** — "Like how Stripe does it." Confirm: *"You mean [specific behavior], right?"*
+- **Energy shifts** — Excitement = signal. Boredom = signal. Weight attention accordingly.
 
 ### Step 5: Converge on Decisions
 
-When the conversation has covered the key points, summarize what's been decided as a brief prose list, then use `AskUserQuestion` for final confirmation:
+Summarize what's been decided as a brief list, then confirm:
 
-*"Here's where I think we've landed:"*
-- *[Decision 1]: [what was decided and why]*
-- *[Decision 2]: [what was decided and why]*
-- *[Open question]: [what's still unresolved and how to handle it]*
+*"Here's where we've landed:"*
+- *[Decision 1]: [what and why]*
+- *[Decision 2]: [what and why]*
+- *[Open question]: [unresolved + how to handle]*
 
-Then confirm with `AskUserQuestion`:
 ```
-question: "Does this match your understanding? Ready to move to planning?"
+question: "Does this match? Ready to move to planning?"
 header: "Confirm"
 options:
   - label: "Looks good, proceed"
-    description: "Lock these decisions and move to planning phase."
-  - label: "I want to adjust something"
-    description: "Revisit one or more decisions before locking."
+    description: "Lock decisions, move to planning."
+  - label: "Adjust something"
+    description: "Revisit one or more decisions."
   - label: "More to discuss"
-    description: "There are topics we haven't covered yet."
+    description: "Topics we haven't covered yet."
 ```
 
-These decisions flow into `context.md` as **Locked Decisions** when the `planning` skill runs next.
+Decisions flow into `context.md` as **Locked Decisions** when `planning` runs.
 
 ## Post-Planning Discussion
 
-When invoked on an existing phase or plan:
-
 ### Step 1: Load Context
 
-Read the relevant files:
-- The plan being discussed (`.forge/phases/m{M}-{N}-{name}/plan-{NN}.md`)
-- Requirements it's based on (`.forge/requirements.yml`)
-- Locked decisions (`.forge/context.md`)
-- Constitution (`.forge/constitution.md`)
+```
+Read: .forge/phases/m{M}-{N}-{name}/plan-{NN}.md → the plan
+Read: .forge/requirements.yml → source requirements
+Read: .forge/context.md → locked decisions
+Read: .forge/constitution.md → active gates
+```
 
 ### Step 2: Present the Plan in Plain Language
 
-Don't just recite the plan back. Translate it into what it means:
-
-*"Phase 2 has 3 plans with 8 tasks total. Here's what it actually does:*
-
-*Plan 01 builds [feature A] — it creates [these things] and wires them to [these things]. The main risk is [risk]. Estimated at [time].*
+Translate the plan into what it means — don't recite it back.
 
+*"Phase 2 has 3 plans with 8 tasks. Here's what it does:*
+*Plan 01 builds [feature A] — creates [X], wires to [Y]. Main risk: [risk].*
 *Plan 02 builds [feature B] — [same pattern].*
-
-*The key assumption is [assumption]. If that's wrong, plans 02 and 03 would need rework."*
+*Key assumption: [assumption]. If wrong, plans 02-03 need rework."*
 
 ### Step 3: Surface What's Worth Discussing
 
-Don't wait for the user to spot issues. Proactively surface concerns, then **use `AskUserQuestion` for any that have discrete choices:**
+Proactively surface concerns. Use `AskUserQuestion` for discrete choices:
 
-- **Decisions that could go either way** → `AskUserQuestion` with the options and trade-offs
-- **Scope questions** → `AskUserQuestion` (e.g., "Ship admin features in v1?" with "Yes, include" / "Defer to v2" options)
-- **Risks the plan doesn't address** → `AskUserQuestion` (e.g., "Worth adding a fallback?" with "Add fallback" / "Accept risk" options)
-- **Assumptions you're not confident about** → Prose, since these need the user to confirm or correct rather than choose
+- **Decisions that could go either way** → AskUserQuestion with options and trade-offs
+- **Scope questions** → AskUserQuestion (e.g., "Ship admin in v1?" — "Include" / "Defer to v2")
+- **Unaddressed risks** → AskUserQuestion (e.g., "Add fallback?" — "Add" / "Accept risk")
+- **Shaky assumptions** → Prose (needs user to confirm/correct, not choose)
 
 ### Step 4: Drill into Functionality
 
-Use the same **Functionality Distillation** question layers from Pre-Planning Step 4, but now grounded in the concrete plan. Instead of asking about abstract requirements, ask about the specific tasks and how they'll behave:
-
-- *"Task 2 creates the notification service. When a notification fails to send, should the system retry or just log it?"*
-- *"Plan 01 wires the dashboard to the API. Should the dashboard poll for updates, or should changes push in real-time?"*
-- *"The plan has user roles as a task, but the requirements don't specify what each role can do. Can we walk through the permissions?"*
+Apply the **Functionality Distillation** layers from Pre-Planning Step 4, now grounded in concrete tasks:
 
-This is where post-planning discussion earns its keep — the plan makes the feature concrete enough to ask questions that were impossible during pre-planning.
+- *"Task 2 creates the notification service. On send failure — retry or log?"*
+- *"Plan 01 wires dashboard to API. Poll for updates or push real-time?"*
+- *"The plan has user roles but requirements don't specify permissions. Walk through them?"*
 
-### Step 5: Discuss and Revise Direction
+Post-planning discussion earns its keep here — the plan makes features concrete enough for questions impossible during pre-planning.
 
-The user may want to change approach, adjust scope, reorder priorities, ask questions, or approve as-is. Use `AskUserQuestion` to give them a clear way to signal their intent:
+### Step 5: Discuss and Revise
 
 ```
-question: "How would you like to proceed with this plan?"
+question: "How to proceed with this plan?"
 header: "Direction"
 options:
   - label: "Approve as-is"
-    description: "Lock decisions and move to execution."
+    description: "Lock decisions, move to execution."
   - label: "Adjust scope"
     description: "Defer or add features before building."
   - label: "Change approach"
-    description: "Revisit a technical decision in the plan."
+    description: "Revisit a technical decision."
   - label: "More questions"
-    description: "I want to discuss specific parts further."
+    description: "Discuss specific parts further."
 ```
 
-Based on their response, either drill deeper with follow-up `AskUserQuestion` calls or move to summarizing.
+Drill deeper or move to summarizing based on their response.
 
 ### Step 6: Summarize Changes
 
-If the discussion produced changes to the plan direction, summarize as prose:
+If the discussion produced changes:
 
 *"Based on our discussion:*
-- *[Change 1]: [what changed and why]*
-- *[Change 2]: [what changed and why]*
-- *[Unchanged]: [what stays the same]*
+- *[Change 1]: [what and why]*
+- *[Change 2]: [what and why]*
+- *[Unchanged]: [stays the same]*
 
-Then confirm next steps with `AskUserQuestion`:
 ```
-question: "Ready to update the plans, or more to discuss?"
+question: "Ready to update plans, or more to discuss?"
 header: "Next step"
 options:
   - label: "Update plans"
-    description: "Re-plan affected areas with the revised decisions."
+    description: "Re-plan affected areas with revised decisions."
   - label: "More to discuss"
-    description: "There are topics we haven't covered yet."
+    description: "Topics we haven't covered yet."
 ```
 
-If re-planning is needed, route back to the `planning` skill with the discussion summary as input. The planning skill will update plans, requirements, and context.md accordingly.
+If re-planning is needed, route to `planning` with the discussion summary. Planning updates plans, requirements, and context.md.
 
 ## Facilitation Principles
 
-1. **Lead with the interesting question, not the obvious one.** "Should we use React?" is boring if the project already uses React. "Should the dashboard update in real-time or on refresh?" is the real decision.
-
-2. **Name the trade-off, don't hide it.** Every decision has a cost. Saying "Option A is better" without saying "but it takes 2x longer" is dishonest facilitation.
-
-3. **Reference what the user has already told you.** Good facilitators remember. If the user said "I want this done by Friday" three messages ago, factor that into every recommendation.
-
-4. **Know when to stop discussing.** If the user is clear and confident, don't manufacture uncertainty. Some discussions take 2 minutes. That's fine.
-
-5. **Separate "must decide now" from "can decide later."** Not every question needs an answer before planning starts. Flag what can be deferred and what can't.
+1. **Lead with the interesting question.** "Should we use React?" is boring if the project already uses React. "Real-time or on-refresh?" is the real decision.
+2. **Name the trade-off.** "Option A is better" without "but it takes 2x longer" is dishonest facilitation.
+3. **Reference what the user already told you.** "Done by Friday" three messages ago factors into every recommendation.
+4. **Know when to stop.** If the user is clear and confident, don't manufacture uncertainty.
+5. **Separate "must decide now" from "can decide later."** Flag what can be deferred and what can't.
 
 ## Anti-Patterns
 
-- **Analysis paralysis** — discussing for 30 minutes what could be decided in 5. If the user is going in circles, name it: "I think we have enough to move forward. We can revisit after seeing the first implementation."
-- **False facilitation** — asking questions you already know the answer to. If the research clearly points one way, say so.
-- **Premature convergence** — locking decisions before the user has had a chance to think. Don't rush the summary.
-- **Scope creep via discussion** — "While we're at it, should we also..." Keep discussion focused on the work at hand.
-- **Discussion as procrastination** — if the user keeps wanting to discuss but never approves a plan, gently surface the pattern.
+| Pattern | Fix |
+|---------|-----|
+| Analysis paralysis — 30 min on a 5-min decision | Name it: "We have enough to move forward. Revisit after first implementation." |
+| False facilitation — asking questions you know the answer to | If research points one way, say so. |
+| Premature convergence — locking before the user has thought | Don't rush the summary. |
+| Scope creep via discussion — "while we're at it..." | Stay focused on the work at hand. |
+| Discussion as procrastination — never approving a plan | Surface the pattern. |
 
 ## Phase Handoff
 
-After discussion converges on decisions:
+After discussion converges:
 
-1. **Persist decisions** — The decision summary from Step 5 (pre-planning) or Step 6 (post-planning) will flow into `context.md` when the planning skill runs. For post-planning revisions, note the changes clearly so planning can pick them up.
+1. **Persist decisions** — The summary from Step 5 (pre) or Step 6 (post) flows into `context.md` when planning runs. For post-planning revisions, note changes clearly.
 2. **Update state** — Set `current.status` to `planning` (or `architecting` for Full tier) in `.forge/state/milestone-{id}.yml`
 3. **Recommend context clear:**
 
-*"Discussion phase complete. Decisions are captured and will be written to context.md during planning. I recommend clearing context (`/clear`) before starting the {planning/architecting} phase — the planner will load everything it needs from `.forge/` state files.*
-
-*Ready to continue? Clear context and invoke `/forge` to resume."*
+*"Decisions captured. State written. `/clear` then `/forge` to continue with {planning/architecting}."*