324 lines
11 KiB
Markdown
324 lines
11 KiB
Markdown
---
|
|
name: reverse-engineer
|
|
description: Deep codebase analysis to generate 8 comprehensive documentation files. Adapts based on path choice - Greenfield extracts business logic only (tech-agnostic), Brownfield extracts business logic + technical implementation (tech-prescriptive). This is Step 2 of 6 in the reverse engineering process.
|
|
---
|
|
|
|
# Reverse Engineer (Path-Aware)
|
|
|
|
**Step 2 of 6** in the Reverse Engineering to Spec-Driven Development process.
|
|
|
|
**Estimated Time:** 30-45 minutes
|
|
**Prerequisites:** Step 1 completed (`analysis-report.md` and path selection)
|
|
**Output:** 9 comprehensive documentation files in `docs/reverse-engineering/`
|
|
|
|
**Path-Dependent Behavior:**
|
|
- **Greenfield:** Extract business logic only (framework-agnostic)
|
|
- **Brownfield:** Extract business logic + technical implementation details
|
|
|
|
---
|
|
|
|
## When to Use This Skill
|
|
|
|
Use this skill when:
|
|
- You've completed Step 1 (Initial Analysis) with path selection
|
|
- Ready to extract comprehensive documentation from code
|
|
- Path has been chosen (greenfield or brownfield)
|
|
- Preparing to create formal specifications
|
|
|
|
**Trigger Phrases:**
|
|
- "Reverse engineer the codebase"
|
|
- "Generate comprehensive documentation"
|
|
- "Extract business logic" (greenfield)
|
|
- "Document the full implementation" (brownfield)
|
|
|
|
---
|
|
|
|
## What This Skill Does
|
|
|
|
This skill performs deep codebase analysis and generates **9 comprehensive documentation files**.
|
|
|
|
**Content adapts based on your path:**
|
|
|
|
### Path A: Greenfield (Business Logic Only)
|
|
- Focus on WHAT the system does
|
|
- Avoid framework/technology specifics
|
|
- Extract user stories, business rules, workflows
|
|
- Framework-agnostic functional requirements
|
|
- Can be implemented in any tech stack
|
|
|
|
### Path B: Brownfield (Business Logic + Technical)
|
|
- Focus on WHAT and HOW
|
|
- Document exact frameworks, libraries, versions
|
|
- Extract file paths, configurations, schemas
|
|
- Prescriptive technical requirements
|
|
- Enables `/speckit.analyze` validation
|
|
|
|
**9 Documentation Files Generated:**
|
|
|
|
1. **functional-specification.md** - Business logic, requirements, user stories (+ tech details for brownfield)
|
|
2. **integration-points.md** - External services, APIs, dependencies, data flows (single source of truth)
|
|
3. **configuration-reference.md** - Config options (business-level for greenfield, all details for brownfield)
|
|
4. **data-architecture.md** - Data models, API contracts (abstract for greenfield, schemas for brownfield)
|
|
5. **operations-guide.md** - Operational needs (requirements for greenfield, current setup for brownfield)
|
|
6. **technical-debt-analysis.md** - Issues and improvements
|
|
7. **observability-requirements.md** - Monitoring needs (goals for greenfield, current state for brownfield)
|
|
8. **visual-design-system.md** - UI/UX patterns (requirements for greenfield, implementation for brownfield)
|
|
9. **test-documentation.md** - Testing requirements (targets for greenfield, current state for brownfield)
|
|
|
|
---
|
|
|
|
## Configuration Check (FIRST STEP!)
|
|
|
|
**Load state file to check detection type and route:**
|
|
|
|
```bash
|
|
# Check what kind of application we're analyzing
|
|
DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type // .path')
|
|
echo "Detection: $DETECTION_TYPE"
|
|
|
|
# Check extraction approach
|
|
ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path')
|
|
echo "Route: $ROUTE"
|
|
|
|
# Check spec output location (Greenfield only)
|
|
SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
|
|
echo "Writing specs to: $SPEC_OUTPUT"
|
|
|
|
# Create output directories if needed
|
|
if [ "$SPEC_OUTPUT" != "." ]; then
|
|
mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
|
|
mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
|
|
fi
|
|
```
|
|
|
|
**State file structure (new):**
|
|
```json
|
|
{
|
|
"detection_type": "monorepo-service", // What kind of app
|
|
"route": "greenfield", // How to spec it
|
|
"config": {
|
|
"spec_output_location": "~/git/my-new-app",
|
|
"build_location": "~/git/my-new-app",
|
|
"target_stack": "Next.js 15..."
|
|
}
|
|
}
|
|
```
|
|
|
|
**File write locations:**
|
|
|
|
| Route | Spec Output | Where Files Go |
|
|
|-------|-------------|----------------|
|
|
| **Greenfield** | Custom location | `{spec_output_location}/docs/`, `{spec_output_location}/.specify/` |
|
|
| **Greenfield** | Not set (default) | `./docs/reverse-engineering/`, `./.specify/` (current repo) |
|
|
| **Brownfield** | Always current repo | `./docs/reverse-engineering/`, `./.specify/` |
|
|
|
|
**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 |
|
|
|
|
**How it works:**
|
|
- `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)
|
|
|
|
**Examples:**
|
|
- Monorepo Service + Greenfield → Extract what the service does (not React/Express specifics)
|
|
- Monorepo Service + Brownfield → Extract full Express routes, React components, shared utilities
|
|
- Nx App + Greenfield → Extract business logic (not Angular specifics)
|
|
- Nx App + Brownfield → Extract full Nx configuration, Angular components, project graph
|
|
|
|
---
|
|
|
|
## Process Overview
|
|
|
|
### Phase 1: Deep Codebase Analysis
|
|
|
|
**Approach depends on path:**
|
|
|
|
Use the Task tool with `subagent_type=stackshift:code-analyzer` (or `Explore` as fallback) to analyze:
|
|
|
|
#### 1.1 Backend Analysis
|
|
- All API endpoints (method, path, auth, params, purpose)
|
|
- Data models (schemas, types, interfaces, fields)
|
|
- Configuration (env vars, config files, settings)
|
|
- External integrations (APIs, services, databases)
|
|
- Business logic (services, utilities, algorithms)
|
|
|
|
See [operations/backend-analysis.md](operations/backend-analysis.md)
|
|
|
|
#### 1.2 Frontend Analysis
|
|
- All pages/routes (path, purpose, auth requirement)
|
|
- Components catalog (layout, form, UI components)
|
|
- State management (store structure, global state)
|
|
- API client (how frontend calls backend)
|
|
- Styling (design system, themes, component styles)
|
|
|
|
See [operations/frontend-analysis.md](operations/frontend-analysis.md)
|
|
|
|
#### 1.3 Infrastructure Analysis
|
|
- Deployment (IaC tools, configuration)
|
|
- CI/CD (pipelines, workflows)
|
|
- Hosting (cloud provider, services)
|
|
- Database (type, schema, migrations)
|
|
- Storage (object storage, file systems)
|
|
|
|
See [operations/infrastructure-analysis.md](operations/infrastructure-analysis.md)
|
|
|
|
#### 1.4 Testing Analysis
|
|
- Test files (location, framework, coverage)
|
|
- Test types (unit, integration, E2E)
|
|
- Coverage estimates (% covered)
|
|
- Test data (mocks, fixtures, seeds)
|
|
|
|
See [operations/testing-analysis.md](operations/testing-analysis.md)
|
|
|
|
### Phase 2: Generate Documentation
|
|
|
|
Create `docs/reverse-engineering/` directory and generate all 8 documentation files.
|
|
|
|
See [operations/generate-docs.md](operations/generate-docs.md) for templates and guidelines.
|
|
|
|
---
|
|
|
|
## Output Files
|
|
|
|
### 1. functional-specification.md
|
|
**Focus:** Business logic, WHAT the system does (not HOW)
|
|
|
|
**Sections:**
|
|
- Executive Summary (purpose, users, value)
|
|
- Functional Requirements (FR-001, FR-002, ...)
|
|
- User Stories (P0/P1/P2/P3 priorities)
|
|
- Non-Functional Requirements (NFR-001, ...)
|
|
- Business Rules (validation, authorization, workflows)
|
|
- System Boundaries (scope, integrations)
|
|
- Success Criteria (measurable outcomes)
|
|
|
|
**Critical:** Framework-agnostic, testable, measurable
|
|
|
|
### 2. configuration-reference.md
|
|
**Complete inventory** of all configuration:
|
|
- Environment variables
|
|
- Config file options
|
|
- Feature flags
|
|
- Secrets and credentials (how managed)
|
|
- Default values
|
|
|
|
### 3. data-architecture.md
|
|
**All data models and API contracts:**
|
|
- Data models (with field types, constraints, relationships)
|
|
- API endpoints (request/response formats)
|
|
- JSON Schemas
|
|
- GraphQL schemas (if applicable)
|
|
- Database ER diagram (textual)
|
|
|
|
### 4. operations-guide.md
|
|
**How to deploy and maintain:**
|
|
- Deployment procedures
|
|
- Infrastructure overview
|
|
- Monitoring and alerting
|
|
- Backup and recovery
|
|
- Troubleshooting runbooks
|
|
|
|
### 5. technical-debt-analysis.md
|
|
**Issues and improvements:**
|
|
- Code quality issues
|
|
- Missing tests
|
|
- Security vulnerabilities
|
|
- Performance bottlenecks
|
|
- Refactoring opportunities
|
|
|
|
### 6. observability-requirements.md
|
|
**Logging, monitoring, alerting:**
|
|
- What to log (events, errors, metrics)
|
|
- Monitoring requirements (uptime, latency, errors)
|
|
- Alerting rules and thresholds
|
|
- Debugging capabilities
|
|
|
|
### 7. visual-design-system.md
|
|
**UI/UX patterns:**
|
|
- Component library
|
|
- Design tokens (colors, typography, spacing)
|
|
- Responsive breakpoints
|
|
- Accessibility standards
|
|
- User flows
|
|
|
|
### 8. test-documentation.md
|
|
**Testing requirements:**
|
|
- Test strategy
|
|
- Coverage requirements
|
|
- Test patterns and conventions
|
|
- E2E scenarios
|
|
- Performance testing
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
After running this skill, you should have:
|
|
|
|
- ✅ `docs/reverse-engineering/` directory created
|
|
- ✅ All 8 documentation files generated
|
|
- ✅ Comprehensive coverage of all application aspects
|
|
- ✅ Framework-agnostic functional specification
|
|
- ✅ Complete data model documentation
|
|
- ✅ Ready to proceed to Step 3 (Create Specifications)
|
|
|
|
---
|
|
|
|
## Next Step
|
|
|
|
Once all documentation is generated and reviewed, proceed to:
|
|
|
|
**Step 3: Create Specifications** - Use the create-specs skill to transform docs into formal specifications.
|
|
|
|
---
|
|
|
|
## Important Guidelines
|
|
|
|
### Framework-Agnostic Documentation
|
|
|
|
**DO:**
|
|
- Describe WHAT, not HOW
|
|
- Focus on business logic and requirements
|
|
- Use generic terms (e.g., "HTTP API" not "Express routes")
|
|
|
|
**DON'T:**
|
|
- Hard-code framework names in functional specs
|
|
- Describe implementation details in requirements
|
|
- Mix business logic with technical implementation
|
|
|
|
### Completeness
|
|
|
|
Use the Explore agent to ensure you find:
|
|
- ALL API endpoints (not just the obvious ones)
|
|
- ALL data models (including DTOs, types, interfaces)
|
|
- ALL configuration options (check multiple files)
|
|
- ALL external integrations
|
|
|
|
### Quality Standards
|
|
|
|
Each document must be:
|
|
- **Comprehensive** - Nothing important missing
|
|
- **Accurate** - Reflects actual code, not assumptions
|
|
- **Organized** - Clear sections, easy to navigate
|
|
- **Actionable** - Can be used to rebuild the system
|
|
|
|
---
|
|
|
|
## Technical Notes
|
|
|
|
- Use Task tool with `subagent_type=stackshift:code-analyzer` for path-aware extraction
|
|
- Fallback to `subagent_type=Explore` if StackShift agent not available
|
|
- Parallel analysis: Run backend, frontend, infrastructure analysis concurrently
|
|
- Use multiple rounds of exploration for complex codebases
|
|
- Cross-reference findings across different parts of the codebase
|
|
- The `stackshift:code-analyzer` agent understands greenfield vs brownfield routes automatically
|
|
|
|
---
|
|
|
|
**Remember:** This is Step 2 of 6. The documentation you generate here will be transformed into formal specifications in Step 3.
|