@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/find-related-ideas.md

@@ -0,0 +1,271 @@
+<purpose>
+Find pending ideas related to a selected anchor idea using multi-signal scoring. Uses the CLI's Jaccard tag overlap scoring as a first pass, then applies AI-powered semantic similarity and implementation overlap analysis informed by project context. Results are displayed grouped by match level (HIGH/MEDIUM/LOW) with per-idea reasoning. The user can select ideas from results and flow directly into consolidation.
+</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:
+
+```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 the anchor idea ID and optional flags.
+
+- Extract a single numeric positional argument as the anchor idea ID (e.g., `/dgs:find-related-ideas 42` -> anchor_id=42)
+- Check for `--threshold` flag (high|medium|low). If not provided, default to `medium`.
+
+**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 found. Run /dgs:add-idea to capture ideas first.
+```
+Exit workflow.
+
+**If fewer than 2 pending ideas:**
+```
+Only 1 pending idea found. Finding related ideas requires at least 2 pending ideas.
+```
+Exit workflow.
+
+**If ideas exist:** Display them as a numbered list showing ID, title, and tags:
+
+```
+## Pending Ideas
+
+| # | ID | Title | Tags |
+|---|-----|-------|------|
+| 1 | 001 | Add retry logic | api, reliability |
+| 2 | 003 | Handle timeouts | api |
+| 3 | 017 | Circuit breaker | api, reliability |
+```
+
+Use AskUserQuestion: "Which idea would you like to find related ideas for? (enter a single ID, e.g. 42)"
+
+Parse response into the anchor idea ID.
+</step>
+
+<step name="get_tag_overlap_scores">
+Call the CLI to get algorithmic tag overlap scores:
+
+```bash
+SCORES=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas find-related --id ${ANCHOR_ID} --threshold low --raw)
+```
+
+Use `--threshold low` here to get ALL matches (including low). The workflow will apply the user's threshold after AI scoring.
+
+Parse the JSON result. Extract the `anchor` object and `results` array.
+
+The `anchor` object contains:
+- `id`, `title`, `tags`, `body`, `notes`, `discussion_log`, `research_log`
+
+Each result in the `results` array contains:
+- `id`, `title`, `tags`, `match_level`, `ratio`, `shared_tags`, `body`, `notes`, `discussion_log`, `research_log`
+
+**If results is empty:**
+```
+No ideas with tag overlap found for #${ANCHOR_ID}: "${anchor.title}".
+No related ideas to display.
+```
+Exit workflow.
+
+**Load anchor idea docs:**
+
+Derive the anchor idea's docs directory from its file path:
+```bash
+ANCHOR_PATH=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" ideas list --raw 2>/dev/null | jq -r --arg id "${ANCHOR_ID}" '.ideas[] | select(.id == ($id | tonumber)) | .path // empty')
+ANCHOR_DOCS_DIR="$(dirname "${ANCHOR_PATH}")/docs"
+```
+
+If the docs/ directory exists, load supporting documents:
+- **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 3 images for the anchor (scoring context does not need all images).
+- **PDF files** (.pdf): Prefer .txt sidecar (same directory, same basename with .txt extension). If sidecar exists, read it. If no sidecar, read up to 3 pages via Read tool with `pages` parameter.
+- **Other files**: Skip silently.
+
+If docs/ directory does not exist: silent skip -- no docs is normal, do not mention it.
+If any file is unreadable: skip silently.
+
+Store loaded docs as `anchorDocs` for use in the scoring step.
+</step>
+
+<step name="load_project_context">
+Load project context files to inform AI scoring.
+
+```bash
+# Check for codebase docs
+ls ${codebase_dir}/*.md 2>/dev/null
+# Check for product docs
+ls ${project_root}/docs/product/*.md 2>/dev/null
+```
+
+Where `codebase_dir` is `.planning/codebase` (or the project-specific path if in multi-project mode) and `project_root` is the repo root.
+
+Read available context files. Prioritise:
+1. `ARCHITECTURE.md` -- system structure and module boundaries
+2. `STACK.md` -- technology choices
+3. Other codebase docs that describe system areas
+
+These give the AI understanding of the project's technology and structure for assessing implementation overlap.
+
+**If no codebase or product docs exist**, proceed without them. The AI can still assess semantic similarity from idea content alone, and can infer implementation overlap from idea descriptions.
+</step>
+
+<step name="ai_score_relatedness">
+For each candidate idea from the tag overlap results, perform two additional AI assessments.
+
+Read the anchor's body and each candidate's body (available from the CLI results which include `body`, `notes`, `discussion_log`, `research_log` fields).
+
+**Load candidate idea docs for richer scoring:**
+
+For each candidate idea, before evaluating it, check for the candidate's docs/ directory:
+```bash
+CANDIDATE_PATH=$(echo "${result}" | jq -r '.path // empty')
+CANDIDATE_DOCS_DIR="$(dirname "${CANDIDATE_PATH}")/docs"
+```
+
+If the docs/ directory exists, load supporting documents with a lighter approach to manage context budget:
+- **Text files** (.md, .txt) only -- skip images for candidates to stay within context budget. Cap at 2 text docs per candidate.
+- **PDF files**: sidecar preferred, fallback to 3 pages. Cap at 1 PDF per candidate.
+- **Other files**: Skip silently.
+- Missing docs/: silent skip. Unreadable files: skip silently.
+
+**Context budget cap:** Track total loaded files across all candidates. If total loaded context exceeds 20 files across all candidates, stop loading additional candidate docs and score remaining candidates from body/notes/logs only. This prevents context overflow while enriching scoring for the highest tag-overlap matches (processed first).
+
+For each candidate, evaluate:
+
+**1. Semantic similarity** (do the ideas describe the same or overlapping problem/solution space?):
+- Consider: Are they solving the same problem? Complementary problems? Different aspects of the same feature?
+- Look at body content, notes, discussion logs, research logs, and loaded docs (anchor docs in `anchorDocs`, candidate docs if loaded)
+- Anchor docs may reveal full scope via diagrams, screenshots, or reference material that body text alone does not capture
+- Score: HIGH / MEDIUM / LOW / NONE
+
+**2. Implementation overlap** (would implementing these ideas touch the same code/systems?):
+- Using project context (codebase docs) and any architecture diagrams or technical docs from anchor/candidate docs/, assess whether both ideas would modify the same files, modules, or subsystems
+- If no project context available, infer from idea descriptions (e.g., both mention "API endpoints" = likely overlap)
+- Score: HIGH / MEDIUM / LOW / NONE
+
+Do not penalize candidates without docs/ -- absence of docs is normal and should not affect scoring. If a candidate has no docs/, score based on body, notes, and logs alone (existing behavior).
+
+**Combine the three signals** (tag_overlap from CLI, semantic_similarity, implementation_overlap) into a final `composite_level`:
+- If ANY signal is HIGH -> composite = HIGH
+- If 2+ signals are MEDIUM -> composite = HIGH
+- If ANY signal is MEDIUM -> composite = MEDIUM
+- If ANY signal is LOW -> composite = LOW
+- Otherwise -> composite = NONE
+
+**Generate a `reasoning` string** for each candidate explaining WHY it is related (1-2 sentences referencing the specific signals that contributed). Examples:
+- "Both address API failure modes; would modify the same HTTP client module"
+- "Directly complementary -- circuit breaker is the implementation pattern for the anchor's resilience goal"
+- "Similar problem space (API reliability) but focused on client-side retries vs server-side resilience"
+</step>
+
+<step name="apply_threshold_and_group">
+Apply the user's `--threshold` flag to filter the AI-scored results:
+- `--threshold high` -> only composite HIGH
+- `--threshold medium` (default) -> HIGH + MEDIUM
+- `--threshold low` -> HIGH + MEDIUM + LOW
+
+Remove any results with composite_level = NONE.
+
+Group surviving results by composite match level (HIGH first, then MEDIUM, then LOW).
+
+Within each group, sort by the tag overlap ratio descending (as a secondary sort within the same composite level).
+</step>
+
+<step name="display_results">
+Display results grouped by match level:
+
+```
+## Related Ideas for #${ANCHOR_ID}: "${anchor_title}"
+
+### HIGH Match (N ideas)
+
+| ID | Title | Tags | Reasoning |
+|----|-------|------|-----------|
+| 003 | Handle timeouts | api, reliability | Both address API failure modes; would modify the same HTTP client module |
+| 017 | Circuit breaker | api, error-handling | Directly complementary -- circuit breaker is the implementation pattern for #42's resilience goal |
+
+### MEDIUM Match (N ideas)
+
+| ID | Title | Tags | Reasoning |
+|----|-------|------|-----------|
+| 008 | Add retry logic | api | Similar problem space (API reliability) but focused on client-side retries vs server-side resilience |
+
+### Summary
+Found N related ideas: X high, Y medium, Z low matches
+Threshold: ${threshold} (showing ${what_is_shown})
+```
+
+If no results survive the threshold, display:
+```
+No ideas found matching threshold '${threshold}'. Try `--threshold low` to see all matches.
+```
+And exit workflow.
+</step>
+
+<step name="offer_consolidation">
+After displaying results, offer to flow into consolidation.
+
+Use AskUserQuestion:
+- question: "Would you like to consolidate any of these ideas with #${ANCHOR_ID}?\n- Enter idea IDs to consolidate (comma-separated, e.g. 3,17)\n- Type 'no' to skip"
+
+**If user enters IDs:**
+Build the full list of IDs to consolidate: anchor ID + selected IDs.
+
+Execute the consolidation inline by following the steps defined in `deliver-great-systems/workflows/consolidate-ideas.md`:
+1. Validate all selected IDs exist and are in pending state
+2. Load full source content for all ideas (anchor + selected)
+3. AI synthesise a coherent body capturing combined intent
+4. Generate a title (or use --title if provided)
+5. Merge tags (deduplicated union)
+6. Merge discussion logs with `[from #ID]` attribution, chronologically ordered
+7. Merge research logs with `[from #ID]` attribution, chronologically ordered
+8. Merge notes with source attribution
+9. Present synthesised idea for user review (approve/edit/cancel)
+10. Execute via CLI: `node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs ideas consolidate --ids "${ids_csv}" --title "${title}" --body "${body}" --tags "${tags}" [--discussion "${discussion}"] [--research "${research}"] --raw`
+11. Display confirmation output
+
+This satisfies the requirement that discovery flows directly into consolidation without requiring a separate command. The consolidate-ideas workflow already handles all synthesis logic; follow its steps directly rather than re-implementing them.
+
+**Fallback** (only if context window is nearly exhausted): tell the user to run `/dgs:consolidate-ideas ${ANCHOR_ID} ${selected_ids}` and provide the exact command, explaining that a fresh context is needed.
+
+**If user types 'no':**
+```
+Discovery complete. Run `/dgs:consolidate-ideas <ids>` anytime to merge ideas.
+```
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Anchor idea parsed from arguments or selected interactively
+- [ ] --threshold flag parsed (default: medium)
+- [ ] Tag overlap scores retrieved from CLI via `ideas find-related`
+- [ ] Project context files loaded when available (codebase/, docs/product/)
+- [ ] Semantic similarity scored for each candidate (HIGH/MEDIUM/LOW/NONE)
+- [ ] Implementation overlap scored for each candidate (HIGH/MEDIUM/LOW/NONE)
+- [ ] Three signals combined into composite match level
+- [ ] Results filtered by user's threshold
+- [ ] Results displayed grouped by HIGH/MEDIUM/LOW with per-idea reasoning
+- [ ] User offered option to flow into consolidation with selected ideas
+- [ ] Consolidation executed inline following consolidate-ideas workflow steps
+- [ ] Fallback command provided if context window is exhausted
+</success_criteria>

package/deliver-great-systems/workflows/health.md

@@ -0,0 +1,173 @@
+<purpose>
+Validate planning directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans. Optionally repairs auto-fixable issues.
+</purpose>
+
+<context_tier>lite</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 project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="parse_args">
+**Parse arguments:**
+
+Check if `--repair` flag is present in the command arguments.
+
+```
+REPAIR_FLAG=""
+if arguments contain "--repair"; then
+  REPAIR_FLAG="--repair"
+fi
+```
+</step>
+
+<step name="run_health_check">
+**Run health validation:**
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" validate health $REPAIR_FLAG
+```
+
+Parse JSON output:
+- `status`: "healthy" | "degraded" | "broken"
+- `errors[]`: Critical issues (code, message, fix, repairable)
+- `warnings[]`: Non-critical issues
+- `info[]`: Informational notes
+- `repairable_count`: Number of auto-fixable issues
+- `repairs_performed[]`: Actions taken if --repair was used
+</step>
+
+<step name="format_output">
+**Format and display results:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ DGS Health Check
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: N | Warnings: N | Info: N
+```
+
+**If repairs were performed:**
+```
+## Repairs Performed
+
+- ✓ config.json: Created with defaults
+- ✓ STATE.md: Regenerated from roadmap
+```
+
+**If errors exist:**
+```
+## Errors
+
+- [E001] config.json: JSON parse error at line 5
+  Fix: Run /dgs:health --repair to reset to defaults
+
+- [E002] PROJECT.md not found
+  Fix: Run /dgs:new-project to create
+```
+
+**If warnings exist:**
+```
+## Warnings
+
+- [W001] STATE.md references phase 5, but only phases 1-3 exist
+  Fix: Run /dgs:health --repair to regenerate
+
+- [W005] Phase directory "1-setup" doesn't follow NN-name format
+  Fix: Rename to match pattern (e.g., 01-setup)
+```
+
+**If info exists:**
+```
+## Info
+
+- [I001] 02-implementation/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**Footer (if repairable issues exist and --repair was NOT used):**
+```
+---
+N issues can be auto-repaired. Run: /dgs:health --repair
+```
+</step>
+
+<step name="offer_repair">
+**If repairable issues exist and --repair was NOT used:**
+
+Ask user if they want to run repairs:
+
+```
+Would you like to run /dgs:health --repair to fix N issues automatically?
+```
+
+If yes, re-run with --repair flag and display results.
+</step>
+
+<step name="verify_repairs">
+**If repairs were performed:**
+
+Re-run health check without --repair to confirm issues are resolved:
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" validate health
+```
+
+Report final status.
+</step>
+
+</process>
+
+<error_codes>
+
+| Code | Severity | Description | Repairable |
+|------|----------|-------------|------------|
+| E001 | error | Planning directory not found | No |
+| E002 | error | PROJECT.md not found | No |
+| E003 | error | ROADMAP.md not found | No |
+| E004 | error | STATE.md not found | Yes |
+| E005 | error | config.json parse error | Yes |
+| W001 | warning | PROJECT.md missing required section | No |
+| W002 | warning | STATE.md references invalid phase | Yes |
+| W003 | warning | config.json not found | Yes |
+| W004 | warning | config.json invalid field value | No |
+| W005 | warning | Phase directory naming mismatch | No |
+| W006 | warning | Phase in ROADMAP but no directory | No |
+| W007 | warning | Phase on disk but not in ROADMAP | No |
+| W008 | warning | config.json: workflow.nyquist_validation absent (defaults to enabled but agents may skip) | Yes |
+| W009 | warning | Phase has Validation Architecture in RESEARCH.md but no VALIDATION.md | No |
+| W010 | warning | Repo unreachable (directory not found) | No |
+| I001 | info | Plan without SUMMARY (may be in progress) | No |
+| I002 | info | All repos reachable | No |
+
+</error_codes>
+
+<repair_actions>
+
+| Action | Effect | Risk |
+|--------|--------|------|
+| createConfig | Create config.json with defaults | None |
+| resetConfig | Delete + recreate config.json | Loses custom settings |
+| regenerateState | Create STATE.md from ROADMAP structure | Loses session history |
+| addNyquistKey | Add workflow.nyquist_validation: true to config.json | None — matches existing default |
+
+**Not repairable (too risky):**
+- PROJECT.md, ROADMAP.md content
+- Phase directory renaming
+- Orphaned plan cleanup
+
+</repair_actions>