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:

Initial scan: Document core architecture (1-3 hours)
Start working immediately
Per increment: Document → Modify → Update docs
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:

Full analysis (1-4 weeks)
Document all modules, business rules
Create baseline tests
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)

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

Detect Jira usage:

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

Map Jira structure:

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

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.

Project-Specific Learnings

Before starting work, check for project-specific learnings:

Check if skill memory exists for this skill

cat .specweave/skill-memories/brownfield-analyzer.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.

brownfield-analyzer

Safety Notice

Copy this and send it to your AI assistant to learn