* chore(#3560): delete two unreachable workflows, gate reachability in lint discovery-phase.md and plan-milestone-gaps.md shipped to all 19 runtime install trees with no command, agent, or skill referencing them. plan-milestone-gaps' command was deleted by #2790 and the workflow was left behind; discovery-phase's own header claimed a caller in plan-phase.md's mandatory_discovery step, and that step does not exist — plan-phase.md contains zero occurrences of "discovery". docs/INVENTORY.md asserted discovery-phase.md was an alternate entry for /gsd-new-project. new-project.md never referenced it. The row and the matching note sentence are removed across all five locales rather than corrected. Adds rule 6 to lint-command-contract: every shipped workflow must be reachable from a loader, walking the transitive closure over the three reference shapes this repo uses. The closure seeds ONLY from commands/agents/skills, so a workflow that references only itself and a pair that reference only each other are both correctly reported rather than satisfying themselves; a visited set makes reference cycles terminate. The measure is a mention in a LOADER — docs/ and install-tree fixtures deliberately do not count, because scan.md proved a file can be documented and shipped while entirely unreached. Ships blocking, not report-only: #3561 is in this branch's base, so the tree reports 0 unreachable from the start. Closes #3560 * test(#3560): drive rule 6 end-to-end, sweep a stale allowlist, update ADR-0002 Review findings. Rule 6 had no end-to-end coverage: the tests exercised the pure closure with in-memory data, so the wiring — file collection, exit code, diagnostic — was unproven, and #3560's acceptance list explicitly wants a fixture showing the rule FAILS on a planted orphan. Adds an optional --root to lint-command-contract (default behavior unchanged) and four tests driving the real CLI through the process seam against a temp fixture: clean=0, planted orphan=1, orphan referenced only from docs/=1, orphan reachable transitively=0. The docs/ case is what pins the Goodhart defense — a mention outside a loader must not confer reachability. Deletes two tests that were byte-identical to a third and could not assert anything loader-specific, since the closure is source-agnostic by design; that distinction lives in the lint script's file collection and is now covered above. Removes a stale ALLOWLIST entry for discovery-phase.md in planner-language-regression — the exact sweep-miss class rule 6 exists to catch, found in the PR that adds the rule. ADR-0002 described five per-file frontmatter checks; rule 6 is a repo-level reachability graph, so the Decision section now says so. Refs #3560 * test(#3560): cut the bug-3298 test pin on the deleted plan-milestone-gaps workflow The remote runner went red with four failures: tests/phase.test.cjs asserted the plan-milestone-gaps workflow exists and checked its mkdir patterns, so deleting the file broke the test that pinned it. This is the fence the epic describes — the content-sync test IS what keeps an unreachable file alive — and cutting the coupling is what makes the deletion safe. Removes only that arm. The bug-3298 block guards three workflows against phase-dir prefix drift; the import and add-backlog arms and both shared mkdir-pattern helpers are untouched. Worth recording where the sweep failed: my reachability walk covered commands, agents, skills, gsd-core and docs, and lint-removed-but-needed covers .github/workflows, gsd-core, docs and package.json. Neither looks at tests/, so a test-pinned deletion is invisible to both and surfaces only on the remote runner. The how-to added by this PR names that gap explicitly so the next deletion searches tests/ by hand. Refs #3560 * docs(#3560): add a how-to for resolving unreachable-workflow findings * chore(#3560): backfill changeset pr number to 3564 --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -1,298 +0,0 @@
|
||||
<purpose>
|
||||
Execute discovery at the appropriate depth level.
|
||||
Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
|
||||
|
||||
Called from plan-phase.md's mandatory_discovery step with a depth parameter.
|
||||
|
||||
NOTE: For comprehensive ecosystem research ("how do experts build this"), use /gsd:plan-phase --research-phase instead, which produces RESEARCH.md.
|
||||
</purpose>
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
|
||||
RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --default "" 2>/dev/null || echo "")
|
||||
```
|
||||
|
||||
**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
|
||||
|
||||
|
||||
<depth_levels>
|
||||
**This workflow supports three depth levels:**
|
||||
|
||||
| Level | Name | Time | Output | When |
|
||||
| ----- | ------------ | --------- | -------------------------------------------- | ----------------------------------------- |
|
||||
| 1 | Quick Verify | 2-5 min | No file, proceed with verified knowledge | Single library, confirming current syntax |
|
||||
| 2 | Standard | 15-30 min | DISCOVERY.md | Choosing between options, new integration |
|
||||
| 3 | Deep Dive | 1+ hour | Detailed DISCOVERY.md with validation gates | Architectural decisions, novel problems |
|
||||
|
||||
**Depth is determined by plan-phase.md before routing here.**
|
||||
</depth_levels>
|
||||
|
||||
<source_hierarchy>
|
||||
**MANDATORY: Context7 BEFORE WebSearch**
|
||||
|
||||
Claude's training data is 6-18 months stale. Always verify.
|
||||
|
||||
1. **Context7 MCP FIRST** - Current docs, no hallucination
|
||||
2. **Official docs** - When Context7 lacks coverage
|
||||
3. **WebSearch LAST** - For comparisons and trends only
|
||||
|
||||
See ~/.claude/gsd-core/templates/discovery.md `<discovery_protocol>` for full protocol.
|
||||
</source_hierarchy>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="determine_depth">
|
||||
Check the depth parameter passed from plan-phase.md:
|
||||
- `depth=verify` → Level 1 (Quick Verification)
|
||||
- `depth=standard` → Level 2 (Standard Discovery)
|
||||
- `depth=deep` → Level 3 (Deep Dive)
|
||||
|
||||
Route to appropriate level workflow below.
|
||||
</step>
|
||||
|
||||
<step name="level_1_quick_verify">
|
||||
**Level 1: Quick Verification (2-5 minutes)**
|
||||
|
||||
For: Single known library, confirming syntax/version still correct.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Resolve library in Context7:
|
||||
|
||||
```
|
||||
mcp__context7__resolve-library-id with libraryName: "[library]"
|
||||
```
|
||||
|
||||
2. Fetch relevant docs:
|
||||
|
||||
```
|
||||
mcp__context7__query-docs with:
|
||||
- libraryId: [from step 1]
|
||||
- query: [specific concern]
|
||||
```
|
||||
|
||||
3. Verify:
|
||||
|
||||
- Current version matches expectations
|
||||
- API syntax unchanged
|
||||
- No breaking changes in recent versions
|
||||
|
||||
4. **If verified:** Return to plan-phase.md with confirmation. No DISCOVERY.md needed.
|
||||
|
||||
5. **If concerns found:** Escalate to Level 2.
|
||||
|
||||
**Output:** Verbal confirmation to proceed, or escalation to Level 2.
|
||||
</step>
|
||||
|
||||
<step name="level_2_standard">
|
||||
**Level 2: Standard Discovery (15-30 minutes)**
|
||||
|
||||
For: Choosing between options, new external integration.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Identify what to discover:**
|
||||
|
||||
- What options exist?
|
||||
- What are the key comparison criteria?
|
||||
- What's our specific use case?
|
||||
|
||||
2. **Context7 for each option:**
|
||||
|
||||
```
|
||||
For each library/framework:
|
||||
- mcp__context7__resolve-library-id
|
||||
- mcp__context7__query-docs (frame the `query` for API usage vs concepts)
|
||||
```
|
||||
|
||||
3. **Official docs** for anything Context7 lacks.
|
||||
|
||||
4. **WebSearch** for comparisons:
|
||||
|
||||
- "[option A] vs [option B] {current_year}"
|
||||
- "[option] known issues"
|
||||
- "[option] with [our stack]"
|
||||
|
||||
5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
|
||||
|
||||
6. **Create DISCOVERY.md** using ~/.claude/gsd-core/templates/discovery.md structure:
|
||||
|
||||
- Summary with recommendation
|
||||
- Key findings per option
|
||||
- Code examples from Context7
|
||||
- Confidence level (should be MEDIUM-HIGH for Level 2)
|
||||
|
||||
7. Return to plan-phase.md.
|
||||
|
||||
**Output:** `.planning/phases/XX-name/DISCOVERY.md`
|
||||
</step>
|
||||
|
||||
<step name="level_3_deep_dive">
|
||||
**Level 3: Deep Dive (1+ hour)**
|
||||
|
||||
For: Architectural decisions, novel problems, high-risk choices.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. **Scope the discovery** using ~/.claude/gsd-core/templates/discovery.md:
|
||||
|
||||
- Define clear scope
|
||||
- Define include/exclude boundaries
|
||||
- List specific questions to answer
|
||||
|
||||
2. **Exhaustive Context7 research:**
|
||||
|
||||
- All relevant libraries
|
||||
- Related patterns and concepts
|
||||
- Multiple topics per library if needed
|
||||
|
||||
3. **Official documentation deep read:**
|
||||
|
||||
- Architecture guides
|
||||
- Best practices sections
|
||||
- Migration/upgrade guides
|
||||
- Known limitations
|
||||
|
||||
4. **WebSearch for ecosystem context:**
|
||||
|
||||
- How others solved similar problems
|
||||
- Production experiences
|
||||
- Gotchas and anti-patterns
|
||||
- Recent changes/announcements
|
||||
|
||||
5. **Cross-verify ALL findings:**
|
||||
|
||||
- Every WebSearch claim → verify with authoritative source
|
||||
- Mark what's verified vs assumed
|
||||
- Flag contradictions
|
||||
|
||||
6. **Create comprehensive DISCOVERY.md:**
|
||||
|
||||
- Full structure from ~/.claude/gsd-core/templates/discovery.md
|
||||
- Quality report with source attribution
|
||||
- Confidence by finding
|
||||
- If LOW confidence on any critical finding → add validation checkpoints
|
||||
|
||||
7. **Confidence gate:** If overall confidence is LOW, present options before proceeding.
|
||||
|
||||
8. Return to plan-phase.md.
|
||||
|
||||
**Output:** `.planning/phases/XX-name/DISCOVERY.md` (comprehensive)
|
||||
</step>
|
||||
|
||||
<step name="identify_unknowns">
|
||||
**For Level 2-3:** Define what we need to learn.
|
||||
|
||||
Ask: What do we need to learn before we can plan this phase?
|
||||
|
||||
- Technology choices?
|
||||
- Best practices?
|
||||
- API patterns?
|
||||
- Architecture approach?
|
||||
</step>
|
||||
|
||||
<step name="create_discovery_scope">
|
||||
Use ~/.claude/gsd-core/templates/discovery.md.
|
||||
|
||||
Include:
|
||||
|
||||
- Clear discovery objective
|
||||
- Scoped include/exclude lists
|
||||
- Source preferences (official docs, Context7, current year)
|
||||
- Output structure for DISCOVERY.md
|
||||
</step>
|
||||
|
||||
<step name="execute_discovery">
|
||||
Run the discovery:
|
||||
- Use web search for current info
|
||||
- Use Context7 MCP for library docs
|
||||
- Prefer current year sources
|
||||
- Structure findings per template
|
||||
</step>
|
||||
|
||||
<step name="create_discovery_output">
|
||||
Write `.planning/phases/XX-name/DISCOVERY.md`:
|
||||
- Summary with recommendation
|
||||
- Key findings with sources
|
||||
- Code examples if applicable
|
||||
- Metadata (confidence, dependencies, open questions, assumptions)
|
||||
</step>
|
||||
|
||||
<step name="confidence_gate">
|
||||
After creating DISCOVERY.md, check confidence level.
|
||||
|
||||
If confidence is LOW:
|
||||
|
||||
**Text mode (`workflow.text_mode: true` in config or `--text` flag):** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
|
||||
Use AskUserQuestion:
|
||||
|
||||
- header: "Low Conf."
|
||||
- question: "Discovery confidence is LOW: [reason]. How would you like to proceed?"
|
||||
- options:
|
||||
- "Dig deeper" - Do more research before planning
|
||||
- "Proceed anyway" - Accept uncertainty, plan with caveats
|
||||
- "Pause" - I need to think about this
|
||||
|
||||
If confidence is MEDIUM:
|
||||
Inline: "Discovery complete (medium confidence). [brief reason]. Proceed to planning?"
|
||||
|
||||
If confidence is HIGH:
|
||||
Proceed directly, just note: "Discovery complete (high confidence)."
|
||||
</step>
|
||||
|
||||
<step name="open_questions_gate">
|
||||
If DISCOVERY.md has open_questions:
|
||||
|
||||
Present them inline:
|
||||
"Open questions from discovery:
|
||||
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
|
||||
These may affect implementation. Acknowledge and proceed? (yes / address first)"
|
||||
|
||||
If "address first": Gather user input on questions, update discovery.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Discovery complete: .planning/phases/XX-name/DISCOVERY.md
|
||||
Recommendation: [one-liner]
|
||||
Confidence: [level]
|
||||
|
||||
What's next?
|
||||
|
||||
1. Discuss phase context (/gsd:discuss-phase [current-phase])
|
||||
2. Create phase plan (/gsd:plan-phase [current-phase])
|
||||
3. Refine discovery (dig deeper)
|
||||
4. Review discovery
|
||||
|
||||
```
|
||||
|
||||
NOTE: DISCOVERY.md is NOT committed separately. It will be committed with phase completion.
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<success_criteria>
|
||||
**Level 1 (Quick Verify):**
|
||||
- Context7 consulted for library/topic
|
||||
- Current state verified or concerns escalated
|
||||
- Verbal confirmation to proceed (no files)
|
||||
|
||||
**Level 2 (Standard):**
|
||||
- Context7 consulted for all options
|
||||
- WebSearch findings cross-verified
|
||||
- DISCOVERY.md created with recommendation
|
||||
- Confidence level MEDIUM or higher
|
||||
- Ready to inform PLAN.md creation
|
||||
|
||||
**Level 3 (Deep Dive):**
|
||||
- Discovery scope defined
|
||||
- Context7 exhaustively consulted
|
||||
- All WebSearch findings verified against authoritative sources
|
||||
- DISCOVERY.md created with comprehensive analysis
|
||||
- Quality report with source attribution
|
||||
- If LOW confidence findings → validation checkpoints defined
|
||||
- Confidence gate passed
|
||||
- Ready to inform PLAN.md creation
|
||||
</success_criteria>
|
||||
@@ -1,281 +0,0 @@
|
||||
<purpose>
|
||||
Create all phases necessary to close gaps identified by `/gsd:audit-milestone`. Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase. One command creates all fix phases — no manual `/gsd-add-phase` per gap.
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
Read all files referenced by the invoking prompt's execution_context before starting.
|
||||
</required_reading>
|
||||
|
||||
<process>
|
||||
|
||||
## 1. Load Audit Results
|
||||
|
||||
```bash
|
||||
# Find the most recent audit file
|
||||
(ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null || true) | head -1
|
||||
```
|
||||
|
||||
Parse YAML frontmatter to extract structured gaps:
|
||||
- `gaps.requirements` — unsatisfied requirements
|
||||
- `gaps.integration` — missing cross-phase connections
|
||||
- `gaps.flows` — broken E2E flows
|
||||
|
||||
If no audit file exists or has no gaps, error:
|
||||
```
|
||||
No audit gaps found. Run `/gsd:audit-milestone` first.
|
||||
```
|
||||
|
||||
## 2. Prioritize Gaps
|
||||
|
||||
Group gaps by priority from REQUIREMENTS.md:
|
||||
|
||||
| Priority | Action |
|
||||
|----------|--------|
|
||||
| `must` | Create phase, blocks milestone |
|
||||
| `should` | Create phase, recommended |
|
||||
| `nice` | Ask user: include or defer? |
|
||||
|
||||
For integration/flow gaps, infer priority from affected requirements.
|
||||
|
||||
## 3. Group Gaps into Phases
|
||||
|
||||
Cluster related gaps into logical phases:
|
||||
|
||||
**Grouping rules:**
|
||||
- Same affected phase → combine into one fix phase
|
||||
- Same subsystem (auth, API, UI) → combine
|
||||
- Dependency order (fix stubs before wiring)
|
||||
- Keep phases focused: 2-4 tasks each
|
||||
|
||||
**Example grouping:**
|
||||
```
|
||||
Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
|
||||
Gap: Integration Phase 1→3 (Auth not passed to API calls)
|
||||
Gap: Flow "View dashboard" broken at data fetch
|
||||
|
||||
→ Phase 6: "Wire Dashboard to API"
|
||||
- Add fetch to Dashboard.tsx
|
||||
- Include auth header in fetch
|
||||
- Handle response, update state
|
||||
- Render user data
|
||||
```
|
||||
|
||||
## 4. Determine Phase Numbers
|
||||
|
||||
Find highest existing phase:
|
||||
```bash
|
||||
_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
|
||||
# Get sorted phase list, extract last one
|
||||
HIGHEST=$(gsd_run query phases.list --pick directories[-1])
|
||||
```
|
||||
|
||||
New phases continue from there:
|
||||
- If Phase 5 is highest, gaps become Phase 6, 7, 8...
|
||||
|
||||
## 5. Present Gap Closure Plan
|
||||
|
||||
```markdown
|
||||
## Gap Closure Plan
|
||||
|
||||
**Milestone:** {version}
|
||||
**Gaps to close:** {N} requirements, {M} integration, {K} flows
|
||||
|
||||
### Proposed Phases
|
||||
|
||||
**Phase {N}: {Name}**
|
||||
Closes:
|
||||
- {REQ-ID}: {description}
|
||||
- Integration: {from} → {to}
|
||||
Tasks: {count}
|
||||
|
||||
**Phase {N+1}: {Name}**
|
||||
Closes:
|
||||
- {REQ-ID}: {description}
|
||||
- Flow: {flow name}
|
||||
Tasks: {count}
|
||||
|
||||
{If nice-to-have gaps exist:}
|
||||
|
||||
### Deferred (nice-to-have)
|
||||
|
||||
These gaps are optional. Include them?
|
||||
- {gap description}
|
||||
- {gap description}
|
||||
|
||||
---
|
||||
|
||||
Create these {X} phases? (yes / adjust / defer all optional)
|
||||
```
|
||||
|
||||
Wait for user confirmation.
|
||||
|
||||
## 6. Update ROADMAP.md
|
||||
|
||||
Add new phases to current milestone:
|
||||
|
||||
```markdown
|
||||
### Phase {N}: {Name}
|
||||
**Goal:** {derived from gaps being closed}
|
||||
**Requirements:** {REQ-IDs being satisfied}
|
||||
**Gap Closure:** Closes gaps from audit
|
||||
|
||||
### Phase {N+1}: {Name}
|
||||
...
|
||||
```
|
||||
|
||||
## 7. Update REQUIREMENTS.md Traceability Table (REQUIRED)
|
||||
|
||||
For each REQ-ID assigned to a gap closure phase:
|
||||
- Update the Phase column to reflect the new gap closure phase
|
||||
- Reset Status to `Pending`
|
||||
|
||||
Reset checked-off requirements the audit found unsatisfied:
|
||||
- Change `[x]` → `[ ]` for any requirement marked unsatisfied in the audit
|
||||
- Update coverage count at top of REQUIREMENTS.md
|
||||
|
||||
```bash
|
||||
# Verify traceability table reflects gap closure assignments
|
||||
grep -c "Pending" .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 8. Create Phase Directories
|
||||
|
||||
For each new phase (N, N+1, …), resolve the directory name via `init.phase-op` so the `project_code` prefix is honoured:
|
||||
|
||||
```bash
|
||||
INIT=$(gsd_run query init.phase-op "{NN}")
|
||||
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
||||
expected_phase_dir=$(echo "$INIT" | node -e "process.stdout.write(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).expected_phase_dir)")
|
||||
mkdir -p "${expected_phase_dir}"
|
||||
```
|
||||
|
||||
Repeat for each gap-closure phase number. This produces `{CODE}-{NN}-{slug}/` when `project_code` is set in `.planning/config.json`, and `{NN}-{slug}/` otherwise — consistent with all other phase-creation paths.
|
||||
|
||||
## 9. Commit Roadmap and Requirements Update
|
||||
|
||||
```bash
|
||||
gsd_run query commit "docs(roadmap): add gap closure phases {N}-{M}" --files .planning/ROADMAP.md .planning/REQUIREMENTS.md
|
||||
```
|
||||
|
||||
## 10. Offer Next Steps
|
||||
|
||||
```markdown
|
||||
## ✓ Gap Closure Phases Created
|
||||
|
||||
**Phases added:** {N} - {M}
|
||||
**Gaps addressed:** {count} requirements, {count} integration, {count} flows
|
||||
|
||||
---
|
||||
|
||||
## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
|
||||
|
||||
**Plan first gap closure phase**
|
||||
|
||||
`/clear` then:
|
||||
|
||||
`/gsd:plan-phase {N}`
|
||||
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- `/gsd:execute-phase {N}` — if plans already exist
|
||||
- `cat .planning/ROADMAP.md` — see updated roadmap
|
||||
|
||||
---
|
||||
|
||||
**After all gap phases complete:**
|
||||
|
||||
`/gsd:audit-milestone` — re-audit to verify gaps closed
|
||||
`/gsd:complete-milestone {version}` — archive when audit passes
|
||||
```
|
||||
|
||||
</process>
|
||||
|
||||
<gap_to_phase_mapping>
|
||||
|
||||
## How Gaps Become Tasks
|
||||
|
||||
**Requirement gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
id: DASH-01
|
||||
description: "User sees their data"
|
||||
reason: "Dashboard exists but doesn't fetch from API"
|
||||
missing:
|
||||
- "useEffect with fetch to /api/user/data"
|
||||
- "State for user data"
|
||||
- "Render user data in JSX"
|
||||
|
||||
becomes:
|
||||
|
||||
phase: "Wire Dashboard Data"
|
||||
tasks:
|
||||
- name: "Add data fetching"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Add useEffect that fetches /api/user/data on mount"
|
||||
|
||||
- name: "Add state management"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Add useState for userData, loading, error states"
|
||||
|
||||
- name: "Render user data"
|
||||
files: [src/components/Dashboard.tsx]
|
||||
action: "Replace placeholder with userData.map rendering"
|
||||
```
|
||||
|
||||
**Integration gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
from_phase: 1
|
||||
to_phase: 3
|
||||
connection: "Auth token → API calls"
|
||||
reason: "Dashboard API calls don't include auth header"
|
||||
missing:
|
||||
- "Auth header in fetch calls"
|
||||
- "Token refresh on 401"
|
||||
|
||||
becomes:
|
||||
|
||||
phase: "Add Auth to Dashboard API Calls"
|
||||
tasks:
|
||||
- name: "Add auth header to fetches"
|
||||
files: [src/components/Dashboard.tsx, src/lib/api.ts]
|
||||
action: "Include Authorization header with token in all API calls"
|
||||
|
||||
- name: "Handle 401 responses"
|
||||
files: [src/lib/api.ts]
|
||||
action: "Add interceptor to refresh token or redirect to login on 401"
|
||||
```
|
||||
|
||||
**Flow gap → Tasks:**
|
||||
```yaml
|
||||
gap:
|
||||
name: "User views dashboard after login"
|
||||
broken_at: "Dashboard data load"
|
||||
reason: "No fetch call"
|
||||
missing:
|
||||
- "Fetch user data on mount"
|
||||
- "Display loading state"
|
||||
- "Render user data"
|
||||
|
||||
becomes:
|
||||
|
||||
# Usually same phase as requirement/integration gap
|
||||
# Flow gaps often overlap with other gap types
|
||||
```
|
||||
|
||||
</gap_to_phase_mapping>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
|
||||
- [ ] Gaps prioritized (must/should/nice)
|
||||
- [ ] Gaps grouped into logical phases
|
||||
- [ ] User confirmed phase plan
|
||||
- [ ] ROADMAP.md updated with new phases
|
||||
- [ ] REQUIREMENTS.md traceability table updated with gap closure phase assignments
|
||||
- [ ] Unsatisfied requirement checkboxes reset (`[x]` → `[ ]`)
|
||||
- [ ] Coverage count updated in REQUIREMENTS.md
|
||||
- [ ] Phase directories created
|
||||
- [ ] Changes committed (includes REQUIREMENTS.md)
|
||||
- [ ] User knows to run `/gsd:plan-phase` next
|
||||
</success_criteria>
|
||||
Reference in New Issue
Block a user