Reverse Engineer (Route-Aware)

Step 2 of 6 in the Reverse Engineering to Spec-Driven Development process. The 6-step process: 1. Analyze, 2. Reverse Engineer (this skill), 3. Create Specs, 4. Gap Analysis, 5. Implementation Planning, 6. Implementation.

Estimated Time: 30-45 minutes Prerequisites: Step 1 completed (analysis-report.md and route selection in .stackshift-state.json) Output: 11 documentation files in docs/reverse-engineering/

Route-Dependent Behavior:

Greenfield: Extract business logic only (framework-agnostic)
Brownfield: Extract business logic + technical implementation details

Output is the same regardless of implementation framework (Spec Kit, BMAD, or BMAD Auto-Pilot). The framework choice only affects what happens after Step 2.

Configuration Check

Guard: Verify state file exists before proceeding.

if [ ! -f .stackshift-state.json ]; then
  echo "ERROR: .stackshift-state.json not found."
  echo "Step 1 (Initial Analysis) must be completed first. Run /stackshift.analyze to begin."
  exit 1
fi

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

if [ "$DETECTION_TYPE" = "null" ] || [ -z "$DETECTION_TYPE" ]; then
  echo "ERROR: detection_type missing from state file. Re-run /stackshift.analyze."
  exit 1
fi
if [ "$ROUTE" = "null" ] || [ -z "$ROUTE" ]; then
  echo "ERROR: route missing from state file. Re-run /stackshift.analyze."
  exit 1
fi

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

SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
echo "Writing specs to: $SPEC_OUTPUT"

if [ "$SPEC_OUTPUT" != "." ]; then
  mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
  mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
fi

State file structure:

{
  "detection_type": "monorepo-service",
  "route": "greenfield",
  "implementation_framework": "speckit",
  "config": {
    "spec_output_location": "~/git/my-new-app",
    "build_location": "~/git/my-new-app",
    "target_stack": "Next.js 15..."
  }
}

Capture commit hash for incremental updates:

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
echo "Pinning docs to commit: $COMMIT_HASH"

Extraction approach based on detection + route:

Detection Type	+ Greenfield	+ Brownfield
Monorepo Service	Business logic only (tech-agnostic)	Full implementation + shared packages (tech-prescriptive)
Nx App	Business logic only (framework-agnostic)	Full Nx/Angular implementation details
Generic App	Business logic only	Full implementation

detection_type determines WHAT patterns to look for (shared packages, Nx project config, monorepo structure, etc.)
route determines HOW to document them (tech-agnostic vs tech-prescriptive)

Phase 1: Deep Codebase Analysis

Use the Task tool with subagent_type=stackshift:stackshift-code-analyzer:AGENT to perform analysis. If the agent is unavailable, fall back to the Explore agent.

Error recovery: If a subagent fails or returns empty results for a sub-phase, retry once with the Explore agent. If the retry also fails, record the gap with an [ANALYSIS INCOMPLETE] marker and continue with remaining sub-phases.

Missing components: If a sub-phase finds no relevant code (e.g., no frontend in a backend-only service), document the absence in the corresponding output file rather than skipping the sub-phase.

Launch sub-phases 1.1 through 1.6 in parallel using separate subagent invocations. Collect all results before proceeding to Phase 2.

1.1 Backend Analysis

Find all API endpoints and record their method, route, auth requirements, parameters, and purpose.
Catalog every data model including schemas, types, interfaces, and field definitions.
Inventory all configuration sources: env vars, config files, and settings.
Map every external integration: APIs, services, and databases.
Extract business logic from services, utilities, and algorithms.

1.2 Frontend Analysis

List all pages and routes with their purpose and auth requirements.
Catalog all components by category: layout, form, and UI components.
Document state management: store structure and global state patterns.
Map the API client layer: how the frontend calls the backend.
Extract styling patterns: design system, themes, and component styles.

1.3 Infrastructure Analysis

Document deployment configuration: IaC tools, cloud provider, and services.
Map CI/CD pipelines and workflows.
Catalog database setup: type, schema, and migrations.
Identify storage systems: object storage, file systems, and caching.

1.4 Testing Analysis

Locate all test files and identify the testing frameworks in use.
Classify tests by type: unit, integration, and E2E.
Estimate coverage percentages by module.
Catalog test data: mocks, fixtures, and seed data.

1.5 Business Context Analysis

Read README, CONTRIBUTING, and any marketing or landing pages.
Extract package descriptions and repository metadata.
Identify comment patterns indicating user-facing features.
Collect error messages and user-facing strings for persona inference.
Analyze naming conventions to reveal domain concepts.
Examine git history for decision archaeology.

1.6 Decision Archaeology

Inspect dependency manifests (package.json, go.mod, requirements.txt) for technology choices.
Analyze config files (tsconfig, eslint, prettier) for design philosophy.
Review CI/CD configuration for deployment decisions.
Run git blame on key architectural files to identify decision points.
Collect comments with "why" explanations (TODO, HACK, FIXME, NOTE).
Look for rejected alternatives visible in git history or comments.

Progress signal: After all sub-phases complete, log: "Phase 1 complete: Analysis gathered for [list which sub-phases produced results]."

Phase 2: Generate Documentation

Create docs/reverse-engineering/ directory and generate all 11 documentation files. For each file, apply the greenfield or brownfield variant as described in operations/output-file-specs.md. Read that file now for the detailed per-file specifications.

If .stackshift-docs-meta.json already exists, overwrite it completely with fresh metadata.

Step 2.1: Write metadata file FIRST

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
GENERATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

Write docs/reverse-engineering/.stackshift-docs-meta.json:

{
  "commit_hash": "<COMMIT_HASH>",
  "commit_date": "<COMMIT_DATE>",
  "generated_at": "<GENERATED_AT>",
  "doc_count": 11,
  "route": "<greenfield|brownfield>",
  "docs": {
    "functional-specification.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "integration-points.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "configuration-reference.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "data-architecture.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "operations-guide.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "technical-debt-analysis.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "observability-requirements.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "visual-design-system.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "test-documentation.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "business-context.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "decision-rationale.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" }
  }
}

Step 2.2: Add metadata header to each doc

Every generated doc starts with this header after the title:

# [Document Title]

> **Generated by StackShift** | Commit: `<short-hash>` | Date: `<GENERATED_AT>`
> Run `/stackshift.refresh-docs` to update with latest changes.

Step 2.3: Generate files with checkpoints

Generate files in this order, logging progress after each:

Batch 1 (core architecture):

functional-specification.md
data-architecture.md
integration-points.md
configuration-reference.md

After writing files 1-4, log: "Generated 4/11 files (core architecture complete)." Verify the output directory contains 4 files before continuing.

Batch 2 (operations and quality): 5. operations-guide.md 6. technical-debt-analysis.md 7. observability-requirements.md 8. visual-design-system.md 9. test-documentation.md

After writing files 5-9, log: "Generated 9/11 files (operations and quality complete)." Verify the output directory contains 9 files before continuing.

Batch 3 (context and decisions): 10. business-context.md 11. decision-rationale.md

After writing files 10-11, log: "Generated 11/11 files. Phase 2 complete."

Output structure:

docs/reverse-engineering/
├── .stackshift-docs-meta.json
├── functional-specification.md
├── integration-points.md
├── configuration-reference.md
├── data-architecture.md
├── operations-guide.md
├── technical-debt-analysis.md
├── observability-requirements.md
├── visual-design-system.md
├── test-documentation.md
├── business-context.md
└── decision-rationale.md

Success Criteria

All 11 documentation files generated in docs/reverse-engineering/
Comprehensive coverage of all application aspects
Framework-agnostic functional specification (for greenfield)
Complete data model documentation
Business context captured with clear [INFERRED] / [NEEDS USER INPUT] markers
Decision rationale documented with ADR format
Integration points fully mapped with data flow diagrams
.stackshift-docs-meta.json created with commit hash for incremental updates
Each doc has metadata header with commit hash and generation date

Next Step

Once all documentation is generated:

For GitHub Spec Kit (implementation_framework: speckit): Proceed to Step 3 -- use /stackshift.create-specs to transform docs into .specify/ specs.

For BMAD Method (implementation_framework: bmad): Proceed to Step 6 -- hand off to BMAD's *workflow-init. BMAD's PM and Architect agents use the reverse-engineering docs as context.

For BMAD Auto-Pilot (implementation_framework: bmad-autopilot): Proceed to /stackshift.bmad-synthesize to auto-generate BMAD artifacts. The 11 reverse-engineering docs provide ~90% of what BMAD needs.

DO / DON'T

DO:

Describe WHAT the system does, not HOW (especially for greenfield)
Use all available signals for inference: README, comments, naming, config, git history
Mark confidence levels: no marker = confident, [INFERRED] = reasonable inference, [NEEDS USER INPUT] = genuinely unknown
Cross-reference between docs (e.g., tech debt informs trade-offs)
Cite specific evidence for each inference

DON'T:

Hard-code framework names in functional specs (greenfield)
Mix business logic with technical implementation (greenfield)
Fabricate business goals with no supporting evidence
State inferences as facts without marking them
Skip a section because it requires inference -- attempt it and mark confidence

Completeness Checklist

Verify analysis captured:

ALL API endpoints (not just the obvious ones)
ALL data models (including DTOs, types, interfaces)
ALL configuration options (check multiple files)
ALL external integrations
ALL user-facing strings and error messages (for persona/context inference)
ALL config files (for decision rationale inference)

Each document must be comprehensive, accurate, organized, actionable, and honest about inferred vs verified information.