specweave 1.0.256 → 1.0.259

package/plugins/specweave/commands/brownfield-analyzer.md

@@ -1,408 +0,0 @@
----
-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.
-disable-model-invocation: true
----
-
-# 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
-
-```bash
-# 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**:
-```bash
-# Search for Jira references
-grep -r "JIRA" . --include="*.md" --include="*.txt"
-grep -r "jira.atlassian" . --include="*.md"
-```
-
-**Azure DevOps**:
-```bash
-grep -r "dev.azure.com" . --include="*.md"
-grep -r "visualstudio.com" . --include="*.md"
-```
-
-**GitHub Issues**:
-```bash
-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**:
-```bash
-# 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**:
-```markdown
-# 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**:
-```markdown
-# 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**:
-```bash
-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**:
-```bash
-# 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**:
-```bash
-/sw-ado:sync --import
-```
-
-### GitHub Issues → SpecWeave
-
-**Map issues**:
-- Milestone → Feature (FS-XXX)
-- Issue → User Story (US-XXX)
-- Task list → Tasks (T-XXX)
-
-**Sync**:
-```bash
-/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.**
-