@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/discuss-idea.md

@@ -0,0 +1,263 @@
+<purpose>
+Structured, inline conversational workflow for developing and refining an idea. Walks through Understanding, Exploration, and Refinement phases as a thinking partner -- collaborative, opinionated, pushing back like a cofounder brainstorming. The three phases are a framework for Claude, not a visible structure imposed on the user.
+
+Produces a Discussion Log entry in the idea file, commits the result, and suggests next steps based on the agreed Decision tag. When re-discussing a previously-discussed idea, builds on the prior log by jumping straight to unresolved Open Questions.
+</purpose>
+
+<context_tier>planning</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load planning-tier context files with idea scope:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier planning --raw 2>/dev/null)
+```
+</step>
+
+<step name="parse_arguments">
+Parse `$ARGUMENTS` for an idea ID.
+
+- First positional argument: treat as idea ID (e.g., `/dgs:discuss-idea 5` -> id=5)
+- Named flag: `--id N` (e.g., `/dgs:discuss-idea --id 5` -> id=5)
+
+If no ID provided, list pending ideas and prompt for selection:
+
+```bash
+PENDING=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --state pending --raw)
+```
+
+Parse the JSON `ideas` array.
+
+**If empty:**
+```
+No pending ideas to discuss. Run /dgs:add-idea to capture one.
+```
+Exit workflow.
+
+**If ideas exist:** Display them as a numbered list showing ID, title, and tags. Use AskUserQuestion:
+- header: "Select Idea"
+- question: "Which idea would you like to discuss?"
+- Provide the numbered idea options
+
+Extract the selected idea's ID.
+</step>
+
+<step name="load_idea">
+Load the full idea content by ID:
+
+```bash
+LIST=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas list --raw)
+```
+
+Find the idea in the JSON by matching `id`. If not found:
+```
+Idea #${id} not found.
+```
+Exit workflow.
+
+Read the idea file directly using the `path` from the list result to get the full content including Discussion Log, Research Log, Notes, and body.
+
+Set variables from the parsed content:
+- `id` -- idea ID
+- `title` -- idea title
+- `body` -- idea body/problem statement
+- `tags` -- tags array
+- `notes` -- Notes section content (if any)
+- `state` -- current state (pending, done, rejected)
+- `filename` -- file name
+- `path` -- file path
+- `discussionLog` -- Discussion Log section content (if any)
+- `researchLog` -- Research Log section content (if any)
+
+**Load idea supporting documents:**
+
+Derive the idea's docs directory path from the idea's file path:
+```bash
+IDEA_DIR=$(dirname "${path}")
+IDEA_DOCS_DIR="${IDEA_DIR}/docs"
+```
+
+If a flat structure is used (ideas stored as files, not directories), derive from the filename:
+```bash
+IDEA_SLUG=$(echo "${filename}" | sed 's/^[0-9]*-//' | sed 's/\.md$//')
+IDEA_DOCS_DIR="$(dirname "$(dirname "${path}")")/docs/ideas/pending/${IDEA_SLUG}"
+```
+
+Check both paths. Use whichever exists.
+
+If the docs/ directory exists, list its contents:
+```bash
+ls "${IDEA_DOCS_DIR}/" 2>/dev/null
+```
+
+For each file found, apply the standard docs/ loading pattern:
+- **Text files** (.md, .txt, .json, .yaml, .yml): Read using the Read tool.
+- **Image files** (.png, .jpg, .jpeg, .gif, .svg, .webp): Read using the Read tool directly for multimodal context. Cap at 5 images per idea.
+- **PDF files** (.pdf): Prefer .txt sidecar (same directory, same basename with .txt extension). If sidecar exists, read it. If no sidecar, read up to 5 pages via Read tool with `pages` parameter.
+- **Other files**: Skip silently.
+
+If the docs/ directory does not exist: silent skip -- no docs is normal, do not mention it.
+If any file is unreadable: skip silently -- do not mention files that cannot be read.
+
+Store loaded docs content as `ideaDocs` for use in the discussion.
+</step>
+
+<step name="discussion_context">
+Present the idea to yourself (Claude) as working context.
+
+**For a new discussion** (no prior Discussion Log):
+Internalize the idea's title, body, tags, any notes, and loaded supporting documents. This is the raw material for discussion.
+
+If `ideaDocs` is not empty, include in the internalized context: "Supporting documents available: [list filenames]". Reference specific docs during the discussion when relevant (e.g., "Looking at the diagram in architecture.png...").
+
+**For a re-discussion** (prior Discussion Log exists):
+Review the prior discussion entries. Identify:
+- Open Questions from the most recent entry -- these are the starting point
+- Prior Decisions -- these are context but not necessarily locked. Use discretion on whether to revisit based on new information
+- Key Insights from prior sessions -- build on these, don't repeat them
+- If `ideaDocs` is not empty, note any supporting documents that may inform open questions or add new context since the last discussion
+
+Each re-discussion produces its own fresh Decision tag regardless of prior status.
+</step>
+
+<step name="understanding_phase">
+**Tone: Thinking partner, collaborative, opinionated -- like a cofounder brainstorming.**
+
+**For a new discussion** (no prior log):
+Restate the idea in your own words to confirm understanding. Then ask clarifying questions about the problem:
+- Who has this problem? How often do they hit it?
+- What's the current workaround?
+- What does success look like?
+
+Challenge vague problem statements and push for specifics. Adapt depth to idea complexity -- simple ideas get quick understanding (1-2 exchanges), complex ideas get deeper probing (3-4 exchanges).
+
+**For a re-discussion** (prior log exists):
+Jump straight to unresolved Open Questions from the last session. Skip restating and re-clarifying unless the prior understanding seems incomplete or wrong.
+
+Use AskUserQuestion for each turn of dialogue. Continue until the problem is well-defined.
+
+**Mid-exit handling:** If the user indicates they want to exit (says "done", "save", "exit", "stop", or changes topic), go to step handle_exit.
+</step>
+
+<step name="exploration_phase">
+Proactively raise considerations the user may not have thought of:
+- Alternative approaches to the problem
+- Potential conflicts with existing functionality (use Grep/Glob to check the codebase if the idea relates to existing features)
+- Scope concerns -- is this bigger than it seems?
+- Edge cases and failure modes
+- Dependencies or prerequisites
+
+When one option is clearly better, recommend it with reasoning. Otherwise present options neutrally and let the user decide.
+
+Continue the back-and-forth dialogue with AskUserQuestion. The developer steers the conversation -- follow their lead on what to explore deeper.
+
+**Mid-exit handling:** If the user indicates they want to exit, go to step handle_exit.
+</step>
+
+<step name="refinement_phase">
+Propose a refined version of the idea:
+
+1. **Refined problem statement** -- sharper, more specific than the original
+2. **Updated approach** -- incorporating insights from the discussion
+3. **Open questions** -- questions that emerged during discussion and remain unresolved
+
+Present this as a proposal for user review. Propose a Decision tag -- one of:
+- **"Ready for research"** -- idea is well-defined, needs feasibility/landscape investigation
+- **"Ready for spec"** -- idea is clear enough to write a formal specification
+- **"Needs more thought"** -- idea has merit but unresolved questions remain
+
+Use AskUserQuestion to present the proposal and get approval.
+
+**If user rejects the proposal:** Revise based on their feedback and present again (one revision attempt). If rejected a second time, save with "Needs more thought" as the Decision tag.
+
+**Mid-exit handling:** If the user indicates they want to exit, go to step handle_exit.
+</step>
+
+<step name="handle_exit">
+**This step handles mid-discussion exit from any of the discussion phases (understanding, exploration, refinement).**
+
+When the user indicates they want to exit:
+
+1. **Always save on exit** -- inform the user: "Saving your progress." Do NOT ask permission.
+2. Use **"Needs more thought"** as the Decision tag for partial discussions.
+3. Do **NOT** update the idea body on partial save -- only write the discussion log entry.
+4. Format the partial save entry based on how far the discussion progressed:
+   - Exited during Understanding: capture what was clarified so far
+   - Exited during Exploration: capture clarifications plus alternatives/considerations raised
+   - Exited during Refinement: capture the near-complete refinement with a note that it was not finalized
+
+Proceed to step save_discussion with `partial = true`.
+</step>
+
+<step name="save_discussion">
+Generate the discussion entry fields:
+
+- `date`: current date in YYYY-MM-DD format
+- `keyInsights`: bullet-pointed list of key insights from the discussion (use `\n- ` separator for each bullet)
+- `refinedProblem`: the refined problem statement (full discussion) or summary of what was discussed (partial)
+- `refinedApproach`: the refined approach (full discussion) or "Not yet refined" (partial)
+- `openQuestions`: bullet-pointed list of open questions (use `\n- ` separator for each bullet)
+- `decision`: the agreed Decision tag (e.g., "Ready for research", "Ready for spec", "Needs more thought")
+
+For **re-discussions**: reference what changed from prior discussion in the keyInsights (e.g., "Revised approach from X to Y").
+
+Format as a JSON string and call:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas discuss-save --id "${id}" --entry '${entryJson}'
+```
+
+The `entryJson` should be a JSON object with these fields:
+```json
+{
+  "date": "YYYY-MM-DD",
+  "keyInsights": "- insight one\n- insight two",
+  "refinedProblem": "The refined problem statement",
+  "refinedApproach": "The refined approach",
+  "openQuestions": "- question one\n- question two",
+  "decision": "Ready for research"
+}
+```
+
+Parse the JSON result to confirm success.
+
+**For FULL discussions only** (not partial saves): If the idea body or approach changed significantly during refinement, also update the idea body:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas update --id "${id}" --field body --value "${refinedBody}"
+```
+
+Per CONTEXT.md: idea body is NOT updated on partial save.
+</step>
+
+<step name="git_commit">
+Commit the updated idea file:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs commit "docs: discuss idea #${id} — ${title}" --files ${path}
+```
+</step>
+
+<step name="suggest_next">
+Based on the Decision tag, suggest the next action:
+
+- **"Ready for research"**: "Run `/dgs:research-idea ${id}` to investigate feasibility and landscape."
+- **"Ready for spec"**: "Run `/dgs:write-spec` to create a formal spec from this idea."
+- **"Needs more thought"**: "Run `/dgs:discuss-idea ${id}` again when you're ready to continue."
+
+For re-discussions, if the Decision tag changed from the prior session, note the progression (e.g., "Progressed from 'Needs more thought' to 'Ready for research'").
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Idea loaded and displayed as context
+- [ ] Three-phase discussion conducted (or partial if user exits early)
+- [ ] Discussion log entry saved to idea file via discuss-save CLI
+- [ ] Updated timestamp refreshed
+- [ ] Git commit created with correct message format
+- [ ] Next steps suggested based on Decision tag
+</success_criteria>