forge-orkes 0.3.10 → 0.3.13

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

@@ -1,31 +1,31 @@
 ---
 name: discussing
-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."
+description: "Talk through approach, trade-offs, or concerns before committing. Between researching/planning, or revisits plans on demand. Decisions only — no plans, no code."
 ---
 
 # Discussing
 
-Structured conversation about approach, trade-offs, and decisions. Produces clarity, not artifacts.
+Structured conversation: approach, trade-offs, decisions. Clarity, not artifacts.
 
 ## When to Invoke
 
 | 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. |
+| Pre-planning | After `researching`, before `planning`. Research available -- decide what to do. |
+| Post-planning | "Discuss Phase 2" or "rethink auth." Plan exists, user revisits. |
+| Mid-workflow | User uncertain -- "wait," "alternatives?" Available from any skill. |
 
 ## Boundaries
 
-- 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.
+- No plans, code, or `.forge/` writes
+- No phase/plan required
+- Only output: conversation + decision summary next skill honors
 
 ## Pre-Planning Discussion
 
 ### Step 0: Load Context
 
-If entering with fresh context (after `/clear`):
+If fresh (after `/clear`):
 
 ```
 Read: .forge/state/milestone-{id}.yml → current position, progress
@@ -34,27 +34,17 @@ Read: .forge/context.md → existing locked decisions (if exists)
 Read: .forge/constitution.md → active gates (if exists)
 ```
 
-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?"*
+Check `.forge/phases/` for research. If inline-only: *"Summarize findings, or re-scan?"*
 
 ### Step 1: Present Decisions with AskUserQuestion
 
-Summarize research structured around decisions — not a data dump.
+Structure around decisions, not data dump. **`AskUserQuestion` per decision**, batch up to 4.
 
-**Use `AskUserQuestion` for every decision point.** Batch up to 4 questions per call.
+Per decision: brief intro (2-3 sentences), then `AskUserQuestion` with `question` (ending `?`), `header` (short label), `options` (2-4, rec first + "(Recommended)", each with trade-off `description`), `multiSelect` (false if exclusive).
 
-For each decision:
-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", "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 into 1-2 calls. Skip for open-ended -- discrete choices only.
 
-**Batch related decisions** into 1-2 calls so the user sees the full landscape.
-
-**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:
+Example:
 
 ```
 Brief context paragraph from research.
@@ -68,21 +58,21 @@ Brief context paragraph from research.
      - "Migration + constraints" / "Let sweep handle it" / ...
 ```
 
-Surface the 3-5 decisions that matter. Not a 20-item matrix.
+Surface 3-5 decisions that matter.
 
 ### Step 2: Facilitate, Don't Dictate
 
-After the user responds, help them think deeper — don't push your preference. Use `AskUserQuestion` for follow-up decisions; prose for open-ended exploration.
+Help user think deeper, don't push preference. `AskUserQuestion` for decisions; prose for open-ended.
 
 | 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 |
+| Name tension, offer AskUserQuestion options | Options as prose paragraphs |
+| Reference earlier decisions to refine later | "What do you think?" without reaction material |
+| `description` names costs | Edge cases before main path clear |
 
-### Step 3: Probe for Hidden Constraints
+### Step 3: Probe Hidden Constraints
 
-Research often misses what the user knows but hasn't mentioned. Use `AskUserQuestion` for structured probes:
+Uncover unstated knowledge. `AskUserQuestion` for structured probes:
 
 ```
 AskUserQuestion:
@@ -97,17 +87,11 @@ AskUserQuestion:
       description: "Do it right, scope is flexible"
 ```
 
-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.
+Open-ended via prose: *"Tried before?" / "Must-haves or must-nots?"* 1-2 at a time.
 
 ### Step 4: Functionality Distillation
 
-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.
-
-**Five question layers per feature/requirement:**
+Per feature, force behavioral clarity. Surface assumptions + edge cases. **Five layers:**
 
 | Layer | Focus | When to use |
 |-------|-------|-------------|
@@ -117,35 +101,15 @@ Walk through each major feature and ask targeted questions that force clarity ab
 | 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 1 — Happy Path:**
-- *"When a user triggers this, what do they see first?"*
-- *"What's the sequence?"*
-- *"What confirms it worked?"*
-
-**Layer 2 — Boundaries:**
-- *"Who can do this?"*
-- *"Any limits — how many, how often, how large?"*
-- *"What triggers it — user action, schedule, or reaction?"*
-
-**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 4 — Side Effects:**
-- *"Does anything else need to update?"*
-- *"Should others be notified? How?"*
-- *"Can this be undone?"*
+**L1:** *"See first?" / "Sequence?" / "Confirms success?"*
+**L2:** *"Who can?" / "Limits?" / "Trigger type?"*
+**L3:** *"Invalid/down/cancel?" / "Retry/fail/alert?" / "Concurrent?"*
+**L4:** *"Else updates?" / "Notify?" / "Undo?"*
+**L5:** *"v1 or final?" / "Essential vs nice-to-have?"*
 
-**Layer 5 — Evolution:**
-- *"v1 that expands later, or final shape?"*
-- *"If you cut scope, what's essential vs. nice-to-have?"*
+Not all 5 mechanically. 2-3 questions, deeper on uncertainty. `AskUserQuestion` for discrete; prose to explain.
 
-Don't mechanically walk all 5 layers for every requirement. Ask 2-3 questions at a time, go deeper where answers reveal uncertainty.
-
-Use `AskUserQuestion` for behavior decisions with discrete answers. Use prose when you need the user to describe or explain.
-
-Example — Layer 3 as AskUserQuestion:
+Example -- L3:
 ```
 question: "When the enrichment API is down, what should the system do?"
 header: "Failure mode"
@@ -159,19 +123,14 @@ options:
 ```
 
 **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
+- **Contradictions** -- "Simple" + "12 states." Surface.
+- **Vague** -- "Just work." Push for example.
+- **Assumed knowledge** -- "Like Stripe." Confirm specifics.
+- **Energy shifts** -- Excitement/boredom = signal.
 
-Summarize what's been decided as a brief list, then confirm:
+### Step 5: Converge
 
-*"Here's where we've landed:"*
-- *[Decision 1]: [what and why]*
-- *[Decision 2]: [what and why]*
-- *[Open question]: [unresolved + how to handle]*
+Summarize decided items, then confirm:
 
 ```
 question: "Does this match? Ready to move to planning?"
@@ -185,7 +144,7 @@ options:
     description: "Topics we haven't covered yet."
 ```
 
-Decisions flow into `context.md` as **Locked Decisions** when `planning` runs.
+Decisions flow into `context.md` as **Locked Decisions** at planning.
 
 ## Post-Planning Discussion
 
@@ -198,35 +157,29 @@ Read: .forge/context.md → locked decisions
 Read: .forge/constitution.md → active gates
 ```
 
-### Step 2: Present the Plan in Plain Language
+### Step 2: Present Plan Simply
 
-Translate the plan into what it means — don't recite it back.
+Translate into meaning, don't recite. Example: *"Phase 2: 3 plans, 8 tasks. Plan 01 builds [A] -- creates [X], wires [Y]. Risk: [risk]. Key assumption: [X]. If wrong, 02-03 need rework."*
 
-*"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].*
-*Key assumption: [assumption]. If wrong, plans 02-03 need rework."*
+### Step 3: Surface Concerns
 
-### Step 3: Surface What's Worth Discussing
+`AskUserQuestion` for:
+- **Either-way decisions** -- options + trade-offs
+- **Scope** -- "Ship admin in v1?" / "Include" / "Defer"
+- **Risks** -- "Add fallback?" / "Add" / "Accept"
+- **Shaky assumptions** -- Prose (confirmation, not choice)
 
-Proactively surface concerns. Use `AskUserQuestion` for discrete choices:
+### Step 4: Drill Functionality
 
-- **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)
+Apply **Functionality Distillation** (Step 4 above), grounded in tasks:
 
-### Step 4: Drill into Functionality
+- *"Notification service send failure -- retry or log?"*
+- *"Dashboard-to-API -- poll or push?"*
+- *"Roles but no permissions. Walk through?"*
 
-Apply the **Functionality Distillation** layers from Pre-Planning Step 4, now grounded in concrete tasks:
+Plan makes features concrete enough for questions impossible earlier.
 
-- *"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?"*
-
-Post-planning discussion earns its keep here — the plan makes features concrete enough for questions impossible during pre-planning.
-
-### Step 5: Discuss and Revise
+### Step 5: Revise
 
 ```
 question: "How to proceed with this plan?"
@@ -242,16 +195,11 @@ options:
     description: "Discuss specific parts further."
 ```
 
-Drill deeper or move to summarizing based on their response.
-
 ### Step 6: Summarize Changes
 
-If the discussion produced changes:
+If changes:
 
-*"Based on our discussion:*
-- *[Change 1]: [what and why]*
-- *[Change 2]: [what and why]*
-- *[Unchanged]: [stays the same]*
+List changes and what stayed same.
 
 ```
 question: "Ready to update plans, or more to discuss?"
@@ -263,32 +211,32 @@ options:
     description: "Topics we haven't covered yet."
 ```
 
-If re-planning is needed, route to `planning` with the discussion summary. Planning updates plans, requirements, and context.md.
+Re-plan? Route to `planning` with summary.
 
 ## Facilitation Principles
 
-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.
+1. **Interesting question first.** "Real-time or on-refresh?" beats "Use React?"
+2. **Name trade-off.** "A is better" without "but 2x longer" = dishonest.
+3. **Reference user's words.** "Friday" factors into every rec.
+4. **Stop when clear.** Don't manufacture uncertainty.
+5. **Now vs later.** Flag deferrable vs blocking.
 
 ## Anti-Patterns
 
 | 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. |
+| Analysis paralysis -- 30 min on 5-min decision | "Enough. Revisit post-impl." |
+| False facilitation -- asking known answers | Say what research shows. |
+| Premature convergence -- lock before thinking | Don't rush summary. |
+| Scope creep -- "while we're at it..." | Stay focused. |
+| Procrastination -- never approving | Surface it. |
 
 ## Phase Handoff
 
-After discussion converges:
+After convergence:
 
-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:**
+1. **Persist** -- Step 5/6 summary flows into `context.md` at planning. Post-planning revisions noted.
+2. **Update state** -- `current.status` = `planning` (`architecting` for Full) in milestone yml
+3. **Recommend clear:**
 
 *"Decisions captured. State written. `/clear` then `/forge` to continue with {planning/architecting}."*