brownfield-analyzer

name	brownfield-analyzer
description	Analyzes existing brownfield projects to map documentation to SpecWeave's structure (PRD/HLD/Spec/Runbook). Use when migrating existing projects to SpecWeave, scanning legacy docs, or creating project context maps. Detects external tools (JIRA, ADO, GitHub) and supports incremental or comprehensive migration paths.

Brownfield Analyzer

Self-contained brownfield project analysis for ANY existing codebase.

---

Purpose

Analyze existing projects and create migration plan to SpecWeave structure. Two paths supported: Quick Start (incremental) or Comprehensive (upfront).

---

Two Migration Paths

Path 1: Quick Start (Recommended for Large Projects)

Best for: 50k+ LOC, fast iteration, small teams

Process:

1. Initial scan: Document core architecture (1-3 hours)
2. Start working immediately
3. Per increment: Document → Modify → Update docs
4. Documentation grows with changes

Benefits:

• Start in days, not weeks
• Focus where it matters
• No analysis paralysis

Path 2: Comprehensive Upfront

Best for: <50k LOC, teams, regulated industries

Process:

1. Full analysis (1-4 weeks)
2. Document all modules, business rules
3. Create baseline tests
4. Then start increments

Benefits:

• Complete context upfront
• Full regression coverage
• Team coordination
• Compliance ready

Automatic Recommendation

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)

---

Analysis Workflow

Step 1: Project Assessment

# 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:

• Total files
• Total LOC
• Module count
• Test coverage (if exists)

Output:

📊 Project Analysis
   Files: 1,245
   LOC: 45,678
   Modules: 23
   Tests: 45% coverage

💡 Recommendation: Medium project → User choice (Quick Start or Comprehensive)

Step 2: Document Classification

Scan for documentation:

PRD Candidates (Product Requirements):

• requirements.md, PRD.md, product-spec.md
• docs/product/, specs/requirements/

HLD Candidates (High-Level Design):

• architecture.md, design.md, ARCHITECTURE.md
• docs/architecture/, docs/design/

ADR Candidates (Architecture Decision Records):

• adr/, decisions/, docs/decisions/
• Files with "ADR-" prefix or "decision" in name

Spec Candidates (Technical Specs):

• spec.md, technical-spec.md
• docs/specs/, docs/technical/

Runbook Candidates (Operations):

• runbook.md, operations.md, deployment.md
• docs/ops/, docs/runbooks/

Diagrams:

• *.png, *.svg, *.drawio, *.mmd
• diagrams/, docs/diagrams/

Step 3: External Tool Detection

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"

Step 4: Coding Standards Discovery

Auto-detect:

• ESLint config (.eslintrc, eslint.config.js)
• Prettier config (.prettierrc)
• TypeScript config (tsconfig.json)
• Test config (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

Step 5: Generate Migration Plan

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

---

Migration Checklist

Before SpecWeave Init

• Assess project size (LOC, files)
• Choose path (Quick Start or Comprehensive)
• Backup existing docs
• Identify external tool integrations
• Check coding standards exist

During Migration

Quick Start:

• Document core architecture only
• Create 1-2 critical ADRs
• Set up external tool sync (optional)
• Start first increment immediately

Comprehensive:

• Scan all documentation
• Classify and organize docs
• Create complete module docs
• Document all business rules
• Create ADRs for decisions
• Add baseline tests
• Set up external tool sync

After Migration

• Verify .specweave/ structure exists
• Test increment workflow
• Train team on SpecWeave
• Document migration decisions

---

Document Mapping

Map 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

---

External Tool Migration

Jira → SpecWeave

1. Detect Jira usage:

grep -r "jira" . --include="*.md" | head -5

2. Map Jira structure:

• Epic → Feature (FS-XXX)
• Story → User Story (US-XXX)
• Task → Task (T-XXX)

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)

Azure DevOps → SpecWeave

Map work items:

• Feature → Feature (FS-XXX)
• User Story → User Story (US-XXX)
• Task → Task (T-XXX)

Sync:

/sw-ado:sync --import

GitHub Issues → SpecWeave

Map issues:

• Milestone → Feature (FS-XXX)
• Issue → User Story (US-XXX)
• Task list → Tasks (T-XXX)

Sync:

/sw-github:sync --import

---

Best Practices

✅ DO:

• Choose appropriate path (Quick Start for large projects)
• Document before modifying code
• Migrate incrementally (don't big-bang)
• Preserve existing docs (don't delete)
• Use external tool sync for existing items
• Train team on SpecWeave workflow

❌ DON'T:

• Force Comprehensive for 100k+ LOC projects
• Delete existing documentation
• Migrate all features upfront (Quick Start)
• Skip coding standards discovery
• Ignore external tool integrations
• Over-analyze in Quick Start mode

---

Example: Large Project Migration

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.

---

Example: Small Project Migration

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.

---

Troubleshooting

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.