Gap Analysis (Route-Aware)

Step 4 of 6 in the Reverse Engineering to Spec-Driven Development process.

Estimated Time: 15 minutes Prerequisites: Step 3 completed (.specify/ directory exists with specifications) Output: docs/gap-analysis-report.md

Terminology:

specification = the conceptual document describing a feature
spec.md = the file at .specify/specs/{feature}/spec.md
Spec Kit / /speckit = the GitHub Spec Kit CLI tool

Step 0: Load Configuration

Read .stackshift-state.json to determine route and detection type.

If .stackshift-state.json does not exist, halt execution and inform the user: "Step 1 (Analyze) must be completed before running gap analysis. Run the analyze skill first." Do not proceed without route determination.

if [ ! -f .stackshift-state.json ]; then
  echo "ERROR: .stackshift-state.json not found. Run Step 1 (analyze) first."
  exit 1
fi

DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type // .path')
ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path')

if [ -z "$ROUTE" ] || [ "$ROUTE" = "null" ]; then
  echo "ERROR: No route defined in .stackshift-state.json. Re-run Step 1 (analyze)."
  exit 1
fi

echo "Detection: $DETECTION_TYPE"
echo "Route: $ROUTE"

Routes:

greenfield = building NEW app (tech-agnostic specifications)
brownfield = managing EXISTING app (tech-prescriptive specifications)

Log: "Configuration loaded. Route: $ROUTE, Detection: $DETECTION_TYPE. Proceeding to route-specific analysis."

Based on route, branch to the appropriate section below.

Greenfield Route: Specification Completeness Analysis

Goal: Validate specifications are complete enough to build a NEW application. Not analyzing: Old codebase (building new, not fixing old).

GF-1: Review Specification Completeness

For each spec.md file, check for ambiguities, acceptance criteria, and user stories:

for spec in .specify/specs/*/spec.md; do
  echo "Analyzing: $(basename "$spec")"
  grep "\[NEEDS CLARIFICATION\]" "$spec" || echo "No clarifications needed"
  grep -A 10 "Acceptance Criteria" "$spec" || echo "WARNING: No acceptance criteria found"
  grep -A 5 "User Stories" "$spec" || echo "WARNING: No user stories found"
done

If the .specify/specs/ directory is empty or missing, halt and inform the user: "No specifications found. Run Step 3 (create-specs) first."

Log: "Specification completeness review done. Proceeding to clarification identification."

GF-2: Identify Clarification Needs

Mark ambiguous areas with [NEEDS CLARIFICATION] tags. Common gaps in greenfield specifications:

UI/UX details missing (layout, interactions)
Business rules unclear (edge case behavior)
Data relationships ambiguous (entity modeling)
Non-functional requirements vague (performance, security targets)

GF-3: Ask About Target Tech Stack

Prompt the user to choose a technology stack for the new implementation:

I have validated the specifications extracted from the old codebase.
Now we need to decide what to build the NEW application in.

What tech stack would you like to use?

Examples:
A) Next.js 15 + React 19 + Prisma + PostgreSQL + Vercel
B) Python FastAPI + SQLAlchemy + PostgreSQL + AWS ECS
C) Ruby on Rails 7 + PostgreSQL + Heroku
D) Your choice: [describe your preferred stack]

Document the chosen stack in the project Constitution for consistency.

GF-4: Create Implementation Roadmap

Write the greenfield roadmap to docs/gap-analysis-report.md. Structure the roadmap by build phases (foundation, core features, advanced features). Mark all features as MISSING since greenfield builds from scratch.

Use the template in operations/report-template.md as the output format. Adapt it for greenfield by replacing gap details with build-order phases.

Log: "Greenfield gap analysis complete. Report written to docs/gap-analysis-report.md."

Brownfield Route: Implementation Gap Analysis

Goal: Identify gaps between specifications and EXISTING codebase implementation. Analysis method: AST-powered analysis (primary), Spec Kit (fallback), manual review (last resort).

BF-1: Verify Prerequisites

Check if prerequisite scripts are installed for the fallback analysis path:

if [ ! -f .specify/scripts/bash/check-prerequisites.sh ]; then
  echo "Note: GitHub Spec Kit scripts not found. /speckit.analyze fallback unavailable."
  echo "AST analysis will be the sole automated method."
fi

Log: "Prerequisites checked. Proceeding to analysis."

BF-2a: Run AST-Powered Analysis (PRIMARY)

Run the AST analysis for deep code inspection:

node ~/stackshift/scripts/run-ast-analysis.mjs roadmap . --format=markdown

Failure detection: If this command exits with a non-zero code or produces no output, skip to BF-2b. If it produces output, skip BF-2b and BF-2c entirely.

AST analysis provides:

Function signature verification (not just existence checks)
Stub detection (functions returning placeholder text)
Missing parameter detection
Business logic pattern analysis
Test coverage gaps
Confidence scoring (0-100%)
Phased roadmap with priorities and effort estimates

Log: "AST analysis complete. Found [N] partial, [M] missing features. Proceeding to detailed gap analysis."

BF-2b: Run Spec Kit Analysis (FALLBACK)

Only execute this step if BF-2a produced no output or failed.

> /speckit.analyze

Failure detection: If this command fails with "Script not found" or produces no output, proceed to BF-2c.

Spec Kit checks:

Specifications marked COMPLETE but implementation missing
Implementation exists but not documented in specifications
Inconsistencies between related specifications
Conflicting requirements across specifications
Outdated implementation status

Log: "Spec Kit analysis complete. Proceeding to detailed gap analysis."

BF-2c: Manual Gap Analysis (LAST RESORT)

Only execute this step if both BF-2a and BF-2b failed. Use manual analysis only as a last resort -- it is the least thorough option.

for spec in .specify/specs/*/spec.md; do
  feature=$(dirname "$spec" | xargs basename)
  echo "Analyzing: $feature"
  status=$(grep "^## Status" "$spec" -A 1 | tail -1)
  echo "  Status: $status"
  clarifications=$(grep -c "\[NEEDS CLARIFICATION\]" "$spec" 2>/dev/null || echo "0")
  echo "  Clarifications needed: $clarifications"
  echo ""
done

Log: "Manual analysis complete. Proceeding to detailed gap analysis."

BF-3: Detailed Gap Analysis

For each finding from the analysis (BF-2a, BF-2b, or BF-2c), perform deeper review:

A. Review PARTIAL features. For each partial feature, answer:

What exists? (backend, frontend, tests, docs)
What is missing? (specific components, endpoints, UI)
Why incomplete? (deprioritized, time constraints)
Effort to complete? (hours estimate)
Blockers? (dependencies, unclear requirements)

B. Review MISSING features. For each missing feature, answer:

Is it actually needed? (or can it be deprioritized?)
User impact if missing? (critical, important, nice-to-have)
Implementation complexity? (simple, moderate, complex)
Dependencies? (what must be done first)

C. Assess technical debt from docs/reverse-engineering/technical-debt-analysis.md:

Code quality issues
Missing tests (unit, integration, E2E)
Documentation gaps
Security vulnerabilities
Performance bottlenecks

D. Mark ambiguous areas with [NEEDS CLARIFICATION] tags for unclear requirements, missing UX/UI details, undefined behavior, and unspecified constraints.

Log: "Detailed gap analysis complete. Proceeding to prioritization."

BF-4: Prioritize and Create Roadmap

Assign each gap a priority level using these criteria:

P0 - Critical: Blocking major use cases, security vulnerabilities, data integrity issues, broken core functionality.
P1 - High: Important for core user value, high user impact, competitive differentiation, problematic technical debt.
P2 - Medium: Nice-to-have features, improvements to existing features, minor technical debt, edge cases.
P3 - Low: Future enhancements, polish, non-critical optimizations.

Phase the work into three groups: Phase 1 (P0 items), Phase 2 (P1 features), Phase 3 (P2/P3 enhancements). Estimate hours for each phase.

BF-5: Write Gap Report

Write the report to docs/gap-analysis-report.md using the template in operations/report-template.md. Populate all sections with findings from BF-3 and BF-4.

Log: "Brownfield gap analysis complete. Report written to docs/gap-analysis-report.md."

Post-Analysis: Spec Kit Integration

After writing the gap report, inform the user of these follow-up commands:

/speckit.analyze - Re-run after making changes to track progress
/speckit.tasks {feature} - Generate tasks for a specific feature
/speckit.implement {feature} - Implement a feature step-by-step
/speckit.clarify {feature} - Interactive Q&A to fill specification gaps

Success Criteria

Verify these outputs exist before reporting completion:

AST analysis results reviewed (or fallback method executed)
All inconsistencies documented
PARTIAL features analyzed (what exists vs what is missing)
MISSING features categorized
Technical debt cataloged
[NEEDS CLARIFICATION] markers added where needed
Priorities assigned (P0/P1/P2/P3)
Phased implementation roadmap created
docs/gap-analysis-report.md written
Ready to proceed to Step 5 (Complete Specification)

Next Step

Proceed to Step 5: Complete Specification -- use the complete-spec skill to resolve all [NEEDS CLARIFICATION] markers interactively.