@tekyzinc/gsd-t 2.14.2 → 2.15.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.15.0] - 2026-02-13
+
+### Added
+- `/user:gsd-t-gap-analysis` command — requirements gap analysis against existing codebase
+- Parses spec into discrete numbered requirements, scans codebase, classifies each as implemented/partial/incorrect/not-implemented
+- Evidence-based classification with file:line references for each requirement
+- Severity levels: Critical (incorrect), High (partial), Medium (not implemented), Low (deferrable)
+- Generates `.gsd-t/gap-analysis.md` with requirements breakdown, gap matrix, and summary stats
+- Re-run support with diff against previous gap analysis (resolved, new, changed, unchanged)
+- Optional merge of parsed requirements into `docs/requirements.md`
+- Auto-groups gaps into recommended milestones/features/quick-fixes for promotion
+- Autonomy-aware: Level 3 proceeds with flagged assumptions, Level 1-2 pauses for clarification
+- Total commands: 37 GSD-T + 3 utility = 40
+
 ## [2.14.2] - 2026-02-13
 
 ### Changed

package/README.md

@@ -18,7 +18,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 npx @tekyzinc/gsd-t install
 ```
 
-This installs 36 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
+This installs 37 GSD-T commands + 3 utility commands to `~/.claude/commands/` and the global CLAUDE.md to `~/.claude/CLAUDE.md`. Works on Windows, Mac, and Linux.
 
 ### Start Using It
 
@@ -114,6 +114,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-project` | Full project → milestone roadmap | Manual |
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones | Manual |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md | Manual |
+| `/user:gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 
@@ -279,8 +280,8 @@ get-stuff-done-teams/
 ├── LICENSE
 ├── bin/
 │   └── gsd-t.js                       # CLI installer
-├── commands/                          # 39 slash commands
-│   ├── gsd-t-*.md                     # 36 GSD-T workflow commands
+├── commands/                          # 40 slash commands
+│   ├── gsd-t-*.md                     # 37 GSD-T workflow commands
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives

package/commands/gsd-t-gap-analysis.md

@@ -0,0 +1,203 @@
+# GSD-T: Gap Analysis — Requirements vs. Existing Code
+
+You are performing a gap analysis between a provided specification and the existing codebase. The user pastes requirements or a spec, and you systematically identify what's done, what's partial, what's wrong, and what's missing.
+
+## Step 1: Load Context
+
+Read (if they exist):
+1. `CLAUDE.md` — project context
+2. `.gsd-t/progress.md` — current state
+3. `docs/requirements.md` — existing requirements
+4. `docs/architecture.md` — system structure
+
+## Step 2: Parse Requirements
+
+Break the provided spec into numbered discrete requirements. Each requirement should be:
+- **Atomic** — one testable behavior or capability per item
+- **Clear** — unambiguous language
+- **Categorized** — group related items under section headers
+
+Present the breakdown:
+
+```
+## Parsed Requirements
+
+### {Section 1}
+R1. {Discrete requirement}
+R2. {Discrete requirement}
+
+### {Section 2}
+R3. {Discrete requirement}
+...
+```
+
+For large specs, show progress: "Analyzing section {N} of {total}: {section name}..."
+
+## Step 3: Clarification Check
+
+Review each requirement for ambiguity. If any are unclear:
+
+- At **Level 3 (Full Auto)**: Proceed with reasonable assumptions. Flag each assumption in the gap analysis with `[ASSUMED: {assumption}]`
+- At **Level 1 or 2**: Present the ambiguous items and ask for clarification before proceeding
+
+```
+⚠ {N} requirements need clarification:
+  R{X}: "{requirement}" — {what's unclear}
+  R{Y}: "{requirement}" — {what's unclear}
+
+Discuss now or proceed with assumptions?
+```
+
+## Step 4: System Scan
+
+Scan the existing codebase to understand current state. Read:
+- Source files relevant to each requirement
+- Test files for coverage evidence
+- Configuration and schema files
+- Existing contracts in `.gsd-t/contracts/`
+- Documentation in `docs/`
+
+Build an understanding of what exists before classifying.
+
+## Step 5: Gap Classification
+
+For each requirement, classify with evidence:
+
+| Status | Meaning | Action Needed |
+|--------|---------|---------------|
+| **Implemented** | Code exists and fully matches the requirement | None — verify with tests |
+| **Partial** | Some code exists but incomplete | Finish implementation |
+| **Incorrect** | Code exists but doesn't match the requirement | Fix implementation |
+| **Not Implemented** | No code exists for this requirement | Build from scratch |
+
+Assign severity to gaps:
+
+| Severity | Criteria |
+|----------|----------|
+| **Critical** | Incorrect implementation — existing code actively contradicts the requirement |
+| **High** | Partial implementation — core functionality exists but key pieces are missing |
+| **Medium** | Not implemented — required but no code exists yet |
+| **Low** | Not implemented — nice-to-have or can be deferred |
+
+## Step 6: Generate Gap Analysis Document
+
+Create `.gsd-t/gap-analysis.md`:
+
+```markdown
+# Gap Analysis
+
+## Project: {project name}
+## Date: {date}
+## Spec Source: {brief description of the provided spec}
+
+## Requirements Breakdown
+
+### {Section 1}
+| ID | Requirement | Status | Severity | Evidence |
+|----|-------------|--------|----------|----------|
+| R1 | {requirement} | Implemented | — | `src/auth/login.ts:45` handles email login |
+| R2 | {requirement} | Partial | High | `src/auth/login.ts` has login but no password reset flow |
+| R3 | {requirement} | Incorrect | Critical | `src/auth/session.ts:20` uses localStorage instead of httpOnly cookies |
+| R4 | {requirement} | Not Implemented | Medium | No code found for this feature |
+
+### {Section 2}
+| ID | Requirement | Status | Severity | Evidence |
+|----|-------------|--------|----------|----------|
+...
+
+## Summary
+
+| Status | Count | % |
+|--------|-------|---|
+| Implemented | {n} | {%} |
+| Partial | {n} | {%} |
+| Incorrect | {n} | {%} |
+| Not Implemented | {n} | {%} |
+| **Total** | **{n}** | **100%** |
+
+## Assumptions Made
+- R{X}: {assumption made during analysis}
+- R{Y}: {assumption made during analysis}
+
+## Recommended Actions
+
+### Milestone: {recommended name}
+- R{X}: {brief description} (Severity: {level})
+- R{Y}: {brief description} (Severity: {level})
+
+### Feature: {recommended name}
+- R{X}: {brief description} (Severity: {level})
+
+### Quick Fixes
+- R{X}: {brief description} (Severity: {level})
+```
+
+## Step 7: Merge to Requirements (Optional)
+
+After generating the gap analysis, offer:
+
+```
+Gap analysis complete: {implemented}/{total} requirements met ({%}%).
+{critical} critical, {high} high, {medium} medium, {low} low severity gaps.
+
+Merge parsed requirements into docs/requirements.md? (Y/N)
+```
+
+If yes, merge the discrete requirements into `docs/requirements.md`, marking each with its current status.
+
+## Step 8: Present Promotion Options
+
+Show the recommended groupings and offer promotion paths:
+
+```
+## Recommended Next Steps
+
+1. {Milestone name} — {N} gaps ({critical} critical, {high} high)
+   → /user:gsd-t-milestone "{name}"
+
+2. {Feature name} — {N} gaps
+   → /user:gsd-t-feature "{name}"
+
+3. Quick fixes — {N} items
+   → /user:gsd-t-quick "{description}"
+
+Promote any of these now, or review the gap analysis first?
+```
+
+At **Level 3**: Present the recommendations and wait for user direction. Do NOT auto-promote — the user decides which gaps to act on.
+
+## Step 9: Re-run Support
+
+If `.gsd-t/gap-analysis.md` already exists from a previous run:
+
+1. Read the previous gap analysis
+2. After generating the new one, produce a diff summary:
+
+```
+## Changes Since Last Analysis ({previous date})
+
+### Resolved (were gaps, now implemented)
+- R{X}: {requirement}
+
+### New Gaps (not in previous analysis)
+- R{X}: {requirement} — {status}
+
+### Changed Status
+- R{X}: {status before} → {status now}
+
+### Unchanged Gaps
+- {N} gaps remain from previous analysis
+```
+
+## Document Ripple
+
+After generating the gap analysis, update affected documentation:
+
+### Always update:
+1. **`.gsd-t/progress.md`** — Log the gap analysis in the Decision Log with date and summary stats
+
+### Check if affected:
+2. **`docs/requirements.md`** — If user approved merge in Step 7
+3. **`.gsd-t/techdebt.md`** — If incorrect implementations were found, add them as tech debt items
+
+$ARGUMENTS

package/commands/gsd-t-help.md

@@ -25,6 +25,7 @@ GETTING STARTED                                                        Manual
   project             New project → requirements → milestone roadmap
   feature             Major feature → impact analysis → milestones
   scan                Deep codebase analysis → techdebt.md
+  gap-analysis        Requirements gap analysis — spec vs. existing code
 
 MILESTONE WORKFLOW                                          [auto] = in wave
 ───────────────────────────────────────────────────────────────────────────────
@@ -183,6 +184,14 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/scan/`, `.gsd-t/techdebt.md`
 - **Use when**: Understanding an existing codebase or auditing technical debt
 
+### gap-analysis
+- **Summary**: Gap analysis — paste a spec, identify what's done, partial, incorrect, or missing
+- **Auto-invoked**: No
+- **Creates**: `.gsd-t/gap-analysis.md`
+- **Reads**: Codebase, `docs/requirements.md`, `docs/architecture.md`, `.gsd-t/contracts/`
+- **Use when**: You have a spec or requirements doc and need to know what's already built vs. what's missing
+- **Features**: Re-run diffing, severity classification, evidence-backed classifications, optional requirements merge, promotable gap groupings
+
 ### milestone
 - **Summary**: Define a specific deliverable milestone within a project
 - **Auto-invoked**: No

package/commands/gsd-t.md

@@ -22,6 +22,7 @@ From `$ARGUMENTS`, classify the request into one of these categories:
 | Run full cycle on current milestone | `gsd-t-wave` | "run it", "execute", "let it rip", "full cycle", "wave" |
 | Debug or investigate a problem | `gsd-t-debug` | "bug", "broken", "not working", "error", "investigate", "why does" |
 | Understand or audit codebase | `gsd-t-scan` | "audit", "analyze", "scan", "tech debt", "what's wrong with" |
+| Compare spec to existing code | `gsd-t-gap-analysis` | "compare", "gap analysis", "spec", "requirements check", "what's implemented", "what's missing" |
 | Explore ideas or rethink approach | `gsd-t-brainstorm` | "brainstorm", "what if", "explore", "rethink", "ideas for" |
 | Help articulate a vague idea | `gsd-t-prompt` | "I want to", "how should I", "help me think about" |
 | Generate or fix project CLAUDE.md | `gsd-t-setup` | "setup CLAUDE.md", "restructure CLAUDE.md" |

package/docs/GSD-T-README.md

@@ -83,6 +83,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-project` | Full project → milestone roadmap | Manual |
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones | Manual |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md | Manual |
+| `/user:gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/user:gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
 | `/user:gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.14.2",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 39 slash commands with backlog management, impact analysis, test sync, and milestone archival",
+  "version": "2.15.0",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 40 slash commands with backlog management, impact analysis, test sync, and milestone archival",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/templates/CLAUDE-global.md

@@ -34,6 +34,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-project` | Full project → milestone roadmap |
 | `/user:gsd-t-feature` | Major feature → impact analysis + milestones |
 | `/user:gsd-t-scan` | Deep codebase analysis → techdebt.md |
+| `/user:gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code |
 | `/user:gsd-t-promote-debt` | Convert debt items to milestones |
 | `/user:gsd-t-setup` | Generate or restructure project CLAUDE.md |
 | `/user:gsd-t-init` | Initialize project structure |