Analyzes existing brownfield projects to map documentation structure to SpecWeave's PRD/HLD/Spec/Runbook pattern. Scans folders, classifies documents, detects external tools (Jira, ADO, GitHub), and creates project context map for just-in-time migration. Activates for brownfield, existing project, migrate, analyze structure, legacy documentation.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Self-contained brownfield project analysis for ANY existing codebase.
Analyze existing projects and create migration plan to SpecWeave structure. Two paths supported: Quick Start (incremental) or Comprehensive (upfront).
Best for: 50k+ LOC, fast iteration, small teams
Process:
Benefits:
Best for: <50k LOC, teams, regulated industries
Process:
Benefits:
| Project Size | LOC | Upfront Effort | Recommended |
|---|---|---|---|
| Small | <10k | 4-8 hours | Comprehensive |
| Medium | 10k-50k | 1-2 weeks | User Choice |
| Large | 50k-200k | 2-4 weeks | Quick Start |
| Very Large | 200k+ | 1-3 months | Quick Start (Mandatory) |
# Scan project
find . -type f -name "*.ts" -o -name "*.js" -o -name "*.py" | wc -l
find . -type f \( -name "*.ts" -o -name "*.js" \) -exec wc -l {} + | awk '{sum+=$1} END {print sum}'
Calculate:
Output:
š Project Analysis
Files: 1,245
LOC: 45,678
Modules: 23
Tests: 45% coverage
š” Recommendation: Medium project ā User choice (Quick Start or Comprehensive)
Scan for documentation:
PRD Candidates (Product Requirements):
requirements.md, PRD.md, product-spec.mddocs/product/, specs/requirements/HLD Candidates (High-Level Design):
architecture.md, design.md, ARCHITECTURE.mddocs/architecture/, docs/design/ADR Candidates (Architecture Decision Records):
adr/, decisions/, docs/decisions/Spec Candidates (Technical Specs):
spec.md, technical-spec.mddocs/specs/, docs/technical/Runbook Candidates (Operations):
runbook.md, operations.md, deployment.mddocs/ops/, docs/runbooks/Diagrams:
*.png, *.svg, *.drawio, *.mmddiagrams/, docs/diagrams/Jira Integration:
# Search for Jira references
grep -r "JIRA" . --include="*.md" --include="*.txt"
grep -r "jira.atlassian" . --include="*.md"
Azure DevOps:
grep -r "dev.azure.com" . --include="*.md"
grep -r "visualstudio.com" . --include="*.md"
GitHub Issues:
grep -r "github.com/.*/issues" . --include="*.md"
Auto-detect:
.eslintrc, eslint.config.js).prettierrc)tsconfig.json)vitest.config, jest.config)Analyze patterns:
# Naming conventions
grep -rh "^export function" src/ | head -20
grep -rh "^export class" src/ | head -20
# Import patterns
grep -rh "^import" src/ | sort | uniq -c | sort -rn | head -10
Quick Start Plan:
# Migration Plan: Quick Start Path
## Phase 1: Initial Setup (1-2 hours)
- [ ] Run `specweave init`
- [ ] Document core architecture only
- [ ] Create 1-2 ADRs for critical decisions
## Phase 2: First Increment (1-3 days)
- [ ] Select first feature to modify
- [ ] Document module before touching
- [ ] Create increment with /sw:increment
- [ ] Implement changes
- [ ] Update docs
## Phase 3: Iterate
- [ ] Repeat per feature
- [ ] Documentation grows organically
Comprehensive Plan:
# Migration Plan: Comprehensive Path
## Phase 1: Documentation Baseline (1-2 weeks)
- [ ] Map all modules to .specweave/docs/internal/modules/
- [ ] Create ADRs for major architectural decisions
- [ ] Document business rules
- [ ] Identify technical debt
## Phase 2: Test Baseline (1 week)
- [ ] Add baseline tests for core functionality
- [ ] Target 60-70% coverage
- [ ] Document test strategy
## Phase 3: Structure Migration (2-3 days)
- [ ] Run `specweave init`
- [ ] Migrate existing docs
- [ ] Organize by SpecWeave structure
## Phase 4: Ready for Increments
- [ ] Start feature work with full context
Quick Start:
Comprehensive:
.specweave/ structure existsMap existing docs to SpecWeave structure:
Existing Structure SpecWeave Structure
āāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
docs/product/ .specweave/docs/internal/strategy/
docs/architecture/ .specweave/docs/internal/architecture/
docs/decisions/ .specweave/docs/internal/architecture/adr/
docs/specs/ .specweave/docs/internal/specs/
docs/runbooks/ .specweave/docs/public/runbooks/
docs/api/ .specweave/docs/public/api-docs/
README.md .specweave/docs/public/README.md
CONTRIBUTING.md .specweave/docs/public/CONTRIBUTING.md
1. Detect Jira usage:
grep -r "jira" . --include="*.md" | head -5
2. Map Jira structure:
3. Sync strategy:
# Option 1: Import existing Jira items
/sw-jira:sync --import
# Option 2: Start fresh, sync new work only
# (Use SpecWeave as source of truth)
Map work items:
Sync:
/sw-ado:sync --import
Map issues:
Sync:
/sw-github:sync --import
ā DO:
ā DON'T:
Scenario: 85k LOC Node.js backend, Jira, 15% test coverage
Recommended: Quick Start
Plan:
Week 1: Setup (2 hours)
- Run specweave init
- Document core architecture (5 modules)
- Create 2 ADRs (database, API design)
- Configure Jira sync
Week 1-2: First Increment
- Select first feature: "Add rate limiting"
- Document rate-limiting module
- Create increment with /sw:increment
- Implement with TDD
- Update docs
Week 3+: Iterate
- Repeat per feature
- Documentation grows to 40% over 3 months
- Eventually covers critical paths
Result: Started working in 2 hours, documentation grows naturally.
Scenario: 8k LOC Python app, GitHub Issues, 60% test coverage
Recommended: Comprehensive Upfront
Plan:
Week 1: Full Documentation (8 hours)
- Document all 5 modules
- Create 8 ADRs
- Map business rules
- Document API contracts
Week 1: Test Baseline (4 hours)
- Add missing unit tests (80% coverage)
- Document test strategy
Week 1: Structure Migration (2 hours)
- Run specweave init
- Migrate existing docs
- Configure GitHub sync
Week 2+: Start Increments
- Full context available
- High confidence changes
Result: 2 weeks to full documentation, then smooth increment workflow.
Issue: Can't find existing documentation
Solution: Check common locations: docs/, wiki/, .github/, Notion exports
Issue: Too many documents to classify Solution: Focus on architecture docs first, skip implementation details
Issue: Conflicting documentation Solution: Use git history to find latest/canonical version
Issue: External tool API limits Solution: Use throttled sync, batch imports
This skill is self-contained and works for ANY brownfield project.