gwt-discussion

name	gwt-discussion
description	Use when an idea, spec question, or implementation gap needs investigation and discussion before deciding how work should proceed.
allowed-tools	Bash, Read, Glob, Grep, Edit, Write
argument-hint	[idea | concern | implementation gap | --deepen SPEC-N]

gwt-discussion

Unified discussion entrypoint for exploration, design clarification, and mid-implementation investigation. Use it before a SPEC exists, while a SPEC or plan is being refined, or when implementation reveals a gap that needs user discussion before work can continue.

Use the current user's language for decision summaries, Discussion TODO, Action Delta, Action Bundle, and any user-facing artifact text generated during this workflow, unless an existing artifact must keep its established language.

gwtd resolution

Before executing any gwtd ... command from this skill or its references, resolve GWT_BIN first: executable GWT_BIN_PATH, then command -v gwtd, then $GWT_PROJECT_ROOT/target/debug/gwtd or ./target/debug/gwtd. Run the command as "$GWT_BIN" ...; if none exists, stop with an actionable gwtd not found error.

When to use

• A rough idea may or may not become a SPEC
• An existing SPEC or plan feels incomplete or wrong
• Mid-implementation work uncovered a gap, inconsistency, or dependency chain
• The next step is unclear and needs investigation before gwt-plan-spec or gwt-build-spec

Do not use this when the work is already decision-complete and ready for planning or implementation. Use gwt-plan-spec or gwt-build-spec directly in that case.

Working artifacts

Keep these artifacts throughout the discussion:

• Intake Memo in conversation context for background, scope, and constraints
• Discussion TODO in conversation context and mirrored to the machine-local work-notes discussion log (~/.gwt/projects/<repo-hash>/work-notes/discussions.md, SPEC-3214); the repo-local .gwt/work/discussions.md and legacy .gwt/discussion.md are read fallbacks only
• Action Delta for changes that are ready to land in spec, plan, issue, or build context
• Action Bundle for the concrete follow-up actions that should happen next

When the discussed work touches multiple Issues/SPECs, the artifact update is not complete until exactly one Primary Execution Owner is selected and every related owner is classified (SPEC-3248 Multi-Issue Primary Owner Bundle):

• bundled-required — must ship in the Primary owner's PR; copy or summarize its required tasks and acceptance into the Primary so a single-Issue Execution launch can implement the full bundled scope without opening every related Issue
• dependent-follow-up — separately deliverable with explicit ordering and blocker notes; never a hidden Primary completion requirement
• reference-only — background reading, not part of the PR's completion

Discussion TODO is not an implementation task list. It tracks unresolved questions, dependency checks, deferred decisions, coverage gaps, exit blockers, the next question to ask, and the depth state for the active proposal.

Evidence is part of the discussion state, not a later implementation detail. Do not mark a proposal [chosen] until its evidence fields prove the outcome without relying on speculation, guesses, or vibes.

Mirror structure inside an active entry in the work-notes discussion log:

## Discussion TODO

### Proposal A - <title> [active|parked|rejected|chosen]
- Summary:
- Open Questions:
- Dependency Checks:
- Deferred Decisions:
- Coverage Checks:
- Exit Blockers:
- Next Question:
- Depth Mode:
- Question Ledger:
- Depth Gate:
- Implementation Proof:
- SPEC/Issue Proof:
- Gap Check Proof:
- Official Docs Proof:
- External Research Proof:
- Evidence Gate:
- Promotable Changes:

Promote an item from Discussion TODO into Action Delta only after the high-impact unknown behind it has been resolved.

Mode contract

• Start the discussion in Plan Mode. If the caller is not already in Plan Mode, enter it before Phase 1 begins.
• Resume paths should also re-enter Plan Mode before continuing the discussion.
• Stay in Plan Mode while investigation, questioning, and artifact shaping are in progress.
• The final discussion result should assume the workflow is about to leave Plan Mode.
• Do not leave Plan Mode before the official discussion result (Action Delta and Action Bundle, or a decision-complete <proposed_plan> when the discussion ends in a plan handoff) is ready.

Exit CLI (Stop-block contract)

SPEC-1935 FR-014p routes Stop events through skill-discussion-stop-check, which inspects the work-notes discussion log and falls back to the repo-local .gwt/work/discussions.md, then legacy .gwt/discussion.md, then blocks Stop (with {"decision":"block","reason":"..."}) while any proposal is still [active] with a non-empty Next Question:, unresolved Exit Blockers:, incomplete proof fields, incomplete depth fields, or an Evidence Gate: that is not complete. Depth fields are incomplete when Question Ledger: is empty, Depth Gate: is missing/open, or Depth Gate: deferred(<reason>) has no reason. To let Stop succeed, mark each proposal explicitly using the exit CLI:

• discuss.resolve JSON operation — active → chosen only after Evidence Gate: complete
• discuss.park JSON operation — active → parked (resume later)
• discuss.reject JSON operation — active → rejected
• discuss.clear_next_question JSON operation — clear only the question line. It does not bypass incomplete evidence.

When the Action Bundle is produced, call the matching exit command for each proposal before stopping. The runtime's stop_hook_active flag (built into Claude Code; shared with Codex via codex_hooks) keeps the handler fail-safe: at most one forced continuation per Stop cycle.

Resume hooks

Managed hook settings in .claude/settings.local.json and .codex/hooks.json may surface unfinished discussion candidates from the work-notes discussion log with repo-local .gwt/work/discussions.md and legacy .gwt/discussion.md fallbacks.

Use this contract:

• Treat a proposal marked [active] with a non-empty Next Question as resumable.
• Prefer SessionStart to surface the resume prompt.
• If the runtime does not emit SessionStart before the first turn, arm a fallback from UserPromptSubmit and surface it after the next Stop.
• Offer exactly Resume discussion, Park proposal, and Dismiss for now.
• Resume discussion continues gwt-discussion before other work proceeds.
• Park proposal changes the matching proposal in the work-notes discussion log from [active] to [parked].
• Dismiss for now suppresses the prompt only for the current agent session. A later session may surface it again.
• PreToolUse may also dispatch workflow-policy before mutating tool calls.
• workflow-policy should allow read-only investigation, but block implementation edits until an owner Issue or SPEC is linked.
• If the owner is a gwt-spec Issue, workflow-policy should block implementation until the owner SPEC cache has non-empty plan and tasks sections; local files alone do not unblock it.

Platform question tool

Use the platform's selection-style question tool instead of naming a single API in the contract.

Platform	Preferred tool
Codex	request_user_input
Claude Code	AskUserQuestionTool
Other runtimes	Closest equivalent selection-style question UI

If no selection UI exists in the current runtime, ask in plain text as the exception path. Keep the same one-question-at-a-time discipline.

Flow

Phase 1: Theme + search

1. Understand the user's concern, idea, or implementation gap.
2. Use the gwt-search skill (a skill, not a PATH command) with 2-3 semantic queries in Japanese and English.
3. Check open SPEC Issues with JSON operation issue.spec.list.
4. If an existing Issue number or URL is already the primary owner, capture it in the Intake Memo.
5. If a clear owner exists, present it before going further.
6. If the clear owner is an existing SPEC, run the Board active-claim preflight before changing the work-notes discussion log or any SPEC/plan artifacts:
   • Read the current Board with JSON operation board.show.
   • Look for active claim entries from another session that mention the same owner (#<N> or SPEC-<N>) or the same phase/topic under discussion.
   • If a matching claim exists, pause the discussion flow and present the conflict: join that session with a Board handoff request, redesign a disjoint work split, or continue only after the user explicitly accepts duplicate risk.
   • Intentional parallel discussion/planning is allowed only when ownership is disjoint. Post a fresh Board claim with a Boundary: line naming the topic, artifacts, or files owned by this session before continuing.
   • Acceptance scenario: Given another session has an active Board claim for SPEC-2008 Phase 24, when gwt-discussion --deepen SPEC-2008 starts, then the preflight reports the claim and requires user confirmation before producing an Action Delta or changing SPEC artifacts.

Phase 2: Investigation

Do not ask the user anything until you have investigated.

• Grep for related functions, types, constants, and commands
• Read the files or artifacts that would change
• If possible, run the code or command to observe actual behavior
• Compare code, SPEC, plan, and issue state when they disagree
• Check official documentation for external APIs, runtimes, operating systems, CLIs, libraries, hooks, or platform behavior that cannot be proven locally
• Use web research when repo-local evidence and official documentation are not enough. For fast-moving operational facts, use X search when available, and record the source account, URL, timestamp, and whether it is first-party

For every potential change surface, map:

| Change | Downstream impact | Upstream prerequisite | Must change together |
|---|---|---|---|
| ... | ... | ... | ... |

Phase 3: Discuss

Present findings first:

• expected vs actual behavior
• dependency chains
• gaps between SPEC, plan, issue, and code
• which proposal is currently active, parked, rejected, or chosen

Ask the user one question at a time about the findings. Wait for their answer before asking the next question.

Use the platform question tool first. Each question should:

• use a selection UI when available
• offer 2-3 mutually exclusive options
• put the recommended option first
• avoid freeform text unless options would distort the decision

After each answer:

• update the Intake Memo
• update the Discussion TODO
• append or refine the active proposal's Question Ledger
• update Depth Gate only when depth coverage is complete or explicitly deferred with a reason
• remove or refine the resolved unknown
• re-rank the remaining unresolved questions
• Ask the next highest-impact question if any remain

Depth Interview Loop

Use this loop for every non-trivial discussion, including ordinary gwt-discussion runs. Do not wait for an explicit --deepen flag when the latest answer leaves high-impact ambiguity.

After every answer:

1. Record what was learned in the Question Ledger.
2. Re-score unresolved unknowns across scope boundary, ownership/integration, failure/edge cases, migration/compatibility, verification/success signal, and alternatives/assumption challenge.
3. Ask the next highest-impact question with the platform question tool when any category can still change implementation, routing, ownership, or verification.
4. Every third question, challenge one premise directly: what breaks if the preferred answer is wrong, delayed, partially implemented, or applied to an adjacent subsystem?
5. Set Depth Gate: complete only when the Question Ledger shows all applicable categories are covered. Use Depth Gate: deferred(<reason>) only when the remaining depth is intentionally out of scope for the current Action Bundle.

Do not treat a small number of questions as a completion signal. A broad or risky discussion may require many rounds. Also do not treat a top-3 priority list as the end of deepening; it is only the next batch to discuss before the remaining backlog is re-ranked.

Discussion Depth Gate

Do not stop because one answer landed or because an arbitrary question count was reached. Re-run this gate after each answer.

Coverage Checks:

• scope boundary
• ownership / integration
• failure / edge case
• migration / compatibility
• verification / success signal

Exit Blockers:

• a high-impact unknown still changes implementation, routing, or ownership
• an applicable coverage category above has not been addressed
• Open Questions, Dependency Checks, or Deferred Decisions still contain unresolved high-impact items
• the latest answer introduced a new high-impact unknown

Question depth ladder:

1. Direction / proposal choice
2. Boundary, exceptions, and failure handling
3. Acceptance, verification, and implementation-affecting detail

Keep asking one question at a time until the relevant coverage categories are closed or explicitly deferred with rationale in Discussion TODO.

When the runtime and user allow delegation, a bounded subagent may be used for objective review of competing proposals. Keep that subagent scoped to independent comparison work and do not let it replace the main discussion flow.

Do not end the discussion after a single answer when unresolved high-impact unknowns still exist.

Evidence Gate

Before producing the final Action Delta / Action Bundle, complete the proof fields for every [active] proposal that will become [chosen].

• Implementation Proof: name the implementation files, logs, commands, or tests inspected or run. If no implementation exists, say what proves that.
• SPEC/Issue Proof: name the owner SPEC / plan / tasks / Issue sections read, including any missing or stale items found.
• Gap Check Proof: explicitly cover scope, ownership/integration, failure/edge cases, migration/compatibility, and verification/success signal.
• Official Docs Proof: cite official documentation checked for external API, runtime, OS, CLI, library, or hook behavior. Use not-applicable: <reason> only for purely local behavior.
• External Research Proof: cite non-official research, issue trackers, web search, or X search when needed. Use not-applicable: <reason> only when official docs and local evidence fully settle the question.
• Evidence Gate: set to complete only when the proposal has no unresolved Exit Blockers: and all proof fields above are non-empty or explicitly not-applicable: <reason>.

Official documentation is the preferred external evidence. X search and X API Search Posts official docs are valid discovery paths for fast-moving facts, but X posts alone are not sufficient for irreversible conclusions unless they are first-party posts with URL and timestamp, or are corroborated by official docs or another primary source.

Phase 4: Design and artifact updates

When the discussion stabilizes, update the right artifacts in one batch.

If new or updated behavior needs a SPEC

• Use references/intake.md for search and routing discipline
• Use references/ddd-modeling.md for Bounded Context and domain modeling
• Register the SPEC via gwt-register-spec (sub-skill, SPEC-2784). The caller prepares title + body file from this discussion's outcome; the sub-skill validates, executes the canonical issue.spec.create → issue.spec.edit → issue.spec.section roundtrip safely, and returns the new Issue number. Add Register Spec to the Action Bundle. Use references/registration.md only when the sub-skill is unavailable; in that case follow its 2-step flow manually and verify issue.spec.section returns non-empty content before handoff.
• Use references/clarification.md to remove high-impact [NEEDS CLARIFICATION] markers
• Use references/deepening.md when the user asks for deeper analysis on an existing SPEC

If the plan is stale but the SPEC is already settled

• Update the owner plan and related planning artifacts in-place
• Capture the confirmed deltas in Action Delta
• Return gwt-plan-spec in the Action Bundle when further planning work is still needed

If implementation can resume

• Update the owner spec / plan / issue context as needed first
• Return Resume Build in the Action Bundle
• Let gwt-build-spec continue with the updated context

If the result is narrower than a SPEC

• Return Update Issue or Write Memory in the Action Bundle
• Use gwt-register-issue or gwt-fix-issue when the GitHub Issue flow should own the next step

Phase 5: Exit

Present the result in this format:

## <Discussion Decision in the current user's language>

Owner: #<number> | SPEC-<id> | "new" | "none"
Reason: <one sentence>

### Intake Memo
- <final bullets>

### Discussion TODO
- Proposal A [active|parked|rejected|chosen]: <state + remaining concern>

### Action Delta
- Update Spec: <what changes>
- Update Plan: <what changes>
- Update Issue: <what changes>
- Resume Build Context: <what the implementer must use>

### Action Bundle
- Register Spec
- Update Spec
- Update Plan
- Resume Build
- Update Issue
- Write Memory
- No Action

Register Spec runs the gwt-register-spec sub-skill (SPEC-2784) to materialize a new SPEC Issue safely. Use it instead of manual issue.spec.create whenever a fresh SPEC owner is needed.

This final result is the handoff point where the workflow may leave Plan Mode.

Action Bundle may contain multiple actions. Examples:

• Update Spec + Update Plan + Resume Build
• Update Issue + No Action
• Write Memory only

Goal Start (after Action Bundle approval)

When the Action Bundle is ready and follow-up work can continue autonomously after user approval, arm a runtime goal from the bundle (SPEC-3050):

1. Build a goal condition from the Action Bundle: one verifiable end state (tests green, lint clean, evidence bundle emitted), the check that proves it, and a turn or time cap (for example "or stop after 20 turns"). The condition must respect gwt's PR gate: stop at "verification handoff ready with a recorded User Verification Result" — never "PR created" or "PR merged".
2. Before the final discussion response stops, write the condition to a temp file and run JSON operation discuss.goal_pending after resolving the chosen proposal. This records Goal State: pending in the work-notes discussion log so the next UserPromptSubmit hook can remind the agent even though the approval arrives in a later turn.
3. In the next turn, if the user approves the Action Bundle and asks the follow-up work to continue autonomously, start the goal per runtime:
   • Codex (goals enabled; gwt launches Codex with --enable goals): call create_goal with the condition as the objective — the goals tool contract allows the model to start a Goal itself.
   • Claude Code (v2.1.139 or later): the built-in /goal command cannot be self-invoked by the agent. Queue it into your own pane instead: JSON operation pane.send with params.text:"/goal <condition>" (resolve GWT_BIN first per the gwtd resolution section). The injected line is submitted automatically when the current turn ends. pane send is self-only: it targets the pane bound to GWT_SESSION_ID and rejects other panes.
4. After a successful goal start, run JSON operation discuss.goal_started. If the user rejects or revises the Action Bundle instead, run JSON operation discuss.goal_skipped before continuing the discussion. If the goal cannot be started (older Claude Code, trust dialog not accepted, goals feature disabled, pane.send failure), run JSON operation discuss.goal_failed, report the failure reason explicitly, print the assembled /goal <condition> line so the user can run it manually, and continue the exit. Goal start failures never block the discussion exit.

Routing notes

• Return gwt-plan-spec when design is stable but planning work remains
• Return gwt-build-spec when implementation should continue
• Return gwt-register-issue when new work should become an Issue instead of a SPEC
• Return gwt-fix-issue when an existing Issue owns the next step

Anti-patterns

• Asking before investigating
• Updating artifacts incrementally in the middle of unresolved discussion
• Turning Discussion TODO into an implementation task list
• Ending after the first answer when high-impact unknowns remain
• Writing code during discussion instead of returning an Action Bundle