gsd-path-discuss

Before executing project helpers, read runtime selection and operating rules.

GSD Path Discussion

Use this skill as an interruptible sidecar to the active GSD Path pipeline. Keep the conversation in the main user thread, ground claims in the repository and the current phase artifacts, and save the exchange before returning the answer.

Routing instructions are caller handoffs under the AGENTS.md handoff rule; tell the user which phase owns the follow-up and never invoke it yourself.

Preconditions and ownership

1. Resolve the project root from the working directory. Read AGENTS.md, WORKFLOW.md, and .project/STATE.md before answering.
2. Require a real .project/STATE.md whose frontmatter contains pipeline: gsd-path/v2. If it is missing, foreign, malformed, or a symlink, stop and tell the user to invoke $gsd-path for ownership recovery. Do not create state merely to hold a discussion.
3. Accept any active milestone phase except shipped: inspect, define, research, decide, roadmap, plan, build, or ship. Use the state status currently recorded on disk. A shipped milestone is archived and must not be reopened by this sidecar; start a new milestone first.
4. Resolve the bundled scripts/discussion_records.py, dialogue template, and answers template to absolute paths. Run its prepare command with the absolute repository and template paths before reading any records. This deterministic helper validates STATE ownership, locks STATE, recovers interrupted paired appends, restores an uncommitted review archive without editing it, creates the exact record pair when absent, and fails on stale or malformed state. Do not reproduce those operations manually.
5. Read only the helper-returned absolute DIALOGUE.md and ANSWERS.md paths.
6. Do not change STATE.md, phase status, INTENT.md, SYNTHESIS.md, PLAN.md, task frontmatter, review verdicts, or archive contents. Discussion can propose a change and name its owner; the owning phase must apply it through its normal gate.

The helper serializes writers and rechecks STATE immediately before a paired publication. Never commit the records: the current phase orchestrator is their checkpoint owner and includes them as append-only bookkeeping in its next normal .project/ checkpoint. The answer's named next owner separately owns the target artifact and disposition receipt.

Grounding and pushback

Use the authority order from AGENTS.md:

• Treat the user's current words as the question, but treat intent vetoes and recorded corrections as hard constraints.
• Treat settled synthesis decisions and the current plan/task contract as governing phase inputs. Surface a conflict; never average sources or quietly override a gate.
• Inspect the relevant implementation, callers, tests, and phase artifacts. Use search to locate evidence, then read the code or run an allowed, meaningful check before claiming behavior. Cite exact repository paths and line numbers when practical. Never describe an unrun command as passing.
• Separate observed fact, inference, recommendation, and user decision. If the premise is weak, push back plainly with the evidence and explain the smallest safer alternative.

Read only the phase-specific inputs needed for the question:

Phase	Start with
inspect	codebase map and docs audit
define	intent and inspection evidence
research	intent, research manifest, and relevant evidence
decide	intent, evidence, and synthesis
roadmap	charter, program synthesis, and the roadmap
plan	intent, synthesis, plan, and affected task contracts
build	intent, synthesis, plan, task frontmatter/logs, wave reviews, and STATE log
ship	intent, plan, task frontmatter, STATE log, and relevant review artifacts

Then inspect the code that can prove or disprove the claim. Do not reread the whole repository when a focused path set answers the question.

Focused research

Use existing .project/research/ evidence first. If the question depends on a current external fact, an unfamiliar library behavior, or an unresolved intent risk, perform focused research during the discussion when the required search or source-reading capability is available. Record the query/scope, checked sources, and confidence in the answer record.

Do not launch the full $gsd-path-research phase from this sidecar. That phase owns a legal state transition and a gated RESEARCH.md handoff; invoking it from an arbitrary phase would bypass the pipeline contract. If the result must become formal milestone evidence, record a [RESEARCH] follow-up and name gsd-path-research as the next owner. If research is unavailable, mark the answer NEEDS-USER or unverifiable instead of filling the gap from memory.

Discussion loop

For each invocation:

1. Identify the current phase/status and discussion thread. Run the helper's threads command to list existing thread ids, topics, and statuses; do not parse DIALOGUE.md for them. Reuse a stable thread id (T###) when the user is continuing a topic; request new for a distinct topic and let the helper allocate its id. Classify the request as a fact check, diagnosis, decision, challenge, progress question, or follow-up request.
2. Gather the smallest sufficient local evidence, then focused research only when needed. Record conflicts and uncertainty before forming a conclusion.
3. Answer in the main conversation. State the conclusion first, then the reasoning, evidence, pushback or alternatives, confidence, and the phase owner for any action. When a formal follow-up is required, tell the user to invoke $gsd-path; the router will route the pending answer to that owner. Do not leave the user with only an owner name or direct phase command. Ask only the next question required to resolve the user's decision; use the host's interactive input facility when available.
4. Before returning, provide the semantic turn fields to the helper's append command as one JSON object via --input, passing the same absolute template paths as prepare. The object requires these non-empty fields: topic, user, assistant, question, status, thread_status, conclusion, reasoning, evidence, research, confidence, unresolved, next_owner, target_artifact, and follow_up. thread is optional: pass an existing T### id to continue a thread, or omit it (or pass new) to let the helper allocate the next thread id. An optional date field overrides the record date (YYYY-MM-DD). Every listed field except user and assistant must be a single line; the helper rejects an incomplete payload and names every missing or multi-line field in one error. The helper allocates D/A ids, reply and supersession links, records the current phase/status, and publishes DIALOGUE.md and ANSWERS.md as a recoverable pair. Preserve the user's message and returned assistant answer verbatim in user and assistant.
5. Use working only when the answer is explicitly provisional or asks another question, NEEDS-USER when a human choice or missing evidence blocks it, and final when it resolves the bounded question or the user accepts/closes the thread. Set Follow-up: required only when a named phase must update the named target artifact; otherwise use none. A final answer record is durable context, not approval to advance a phase.

If the user corrects a fact, sets a veto, or makes a decision, preserve the words verbatim in both the dialogue and answer records and identify which formal artifact the owning phase must update. Such a record uses Follow-up: required; it remains pending until the owner appends a fixed-format Disposition X### receipt. The discussion sidecar never writes its own disposition. After a helper failure, do not claim the dialogue or answer was saved; the next prepare recovers an interrupted paired publication before accepting another turn.

Output contract

Every completed turn leaves these project-local artifacts:

• .project/discuss/DIALOGUE.md — append-only transcript of the exchange.
• .project/discuss/ANSWERS.md — append-only answer and decision records, with final answers clearly marked final.

Keep answer records concise but self-contained: question, phase/status, conclusion, reasoning or pushback, evidence/citations, research used or why it was not needed, confidence, unresolved tags, next owner, target artifact, and follow-up state. Do not duplicate a formal phase handoff or silently edit one on the user's behalf. End the user response with Outcome, Markdown Review links to the resolved absolute DIALOGUE.md and ANSWERS.md paths. For a required follow-up, Next names the pending owner and tells the user to invoke $gsd-path; otherwise it gives the next discussion question or says that no action is required.