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.