Import Brownfield Documentation

Import existing documentation from Notion exports, Confluence, GitHub Wiki, or any markdown folder.

What This Does

Analyzes markdown files in source directory (recursively)
Classifies files based on content:
- Specs - Contains "user story", "acceptance criteria", "feature"
- Modules - Contains "module", "component", "architecture"
- Team - Contains "onboarding", "convention", "workflow"
- Legacy - Everything else (no strong match)
Copies files to appropriate destinations
Creates migration report with classification details
Updates config with import history

Usage

/sw:import-docs <source-path> [options]

Options

--source=<type> - Source type: notion, confluence, wiki, custom (required)
--project=<id> - Target project ID (default: active project)
--preserve-structure - Preserve original folder structure
--dry-run - Preview classification without importing

Examples

Example 1: Notion Export

# Export Notion workspace to /tmp/notion-export/
# Then import:

/sw:import-docs /tmp/notion-export/ --source=notion

# Result:
# 📊 Analysis Results:
#    Total files: 47
#    - Specs: 12 files → specs/
#    - Modules: 18 files → modules/
#    - Team docs: 5 files → team/
#    - Legacy: 12 files → legacy/notion/
# ✅ Import complete!

Example 2: Confluence Export

/sw:import-docs /path/to/confluence/ --source=confluence --project=web-app

# Imports to: projects/web-app/specs/, modules/, team/, legacy/confluence/

Example 3: Dry Run (Preview)

/sw:import-docs /tmp/docs/ --source=custom --dry-run

# Shows classification without importing files
# Use this to preview results before actual import

Example 4: Preserve Structure

/sw:import-docs /path/to/wiki/ --source=wiki --preserve-structure

# Preserves original folder structure:
# legacy/wiki/engineering/backend/auth.md
# legacy/wiki/engineering/frontend/components.md

Supported Sources

Notion

Export Format: Markdown & CSV
Steps:
1. In Notion: Settings → Export → Export all workspace content
2. Choose "Markdown & CSV" format
3. Download ZIP file
4. Extract to folder (e.g., /tmp/notion-export/)
5. Run import command

Confluence

Export Format: HTML or Markdown
Steps:
1. Space tools → Content Tools → Export
2. Choose HTML or Markdown
3. Extract exported files
4. Run import command

GitHub Wiki

Export Format: Git repository
Steps:
1. Clone wiki: git clone https://github.com/user/repo.wiki.git
2. Run import command on cloned directory

Custom (Any Markdown)

Any folder containing .md or .markdown files
Recursive search through subdirectories

Classification Algorithm

Files are classified using keyword analysis:

Specs (70%+ confidence)

Keywords: "user story", "acceptance criteria", "feature", "requirement"
Patterns: "As a [user], I want [goal]", "Given-When-Then"
Example: Feature specs, PRDs, user stories

Modules (70%+ confidence)

Keywords: "module", "component", "service", "architecture"
Patterns: API docs, technical design, integration points
Example: Auth module, payment processing, ML pipeline

Team (70%+ confidence)

Keywords: "onboarding", "convention", "workflow", "pr process"
Patterns: Team processes, coding standards, deployment guides
Example: Onboarding guide, code review checklist

Legacy (<70% confidence)

No strong match to above categories
Uncertain classification
Requires manual review

Destination Folders

Files are imported to:

.specweave/docs/internal/projects/{project}/
├── specs/              ← Specs (spec keywords)
├── modules/            ← Modules (module keywords)
├── team/               ← Team docs (team keywords)
└── legacy/{source}/    ← Legacy (uncertain classification)
    ├── notion/
    ├── confluence/
    ├── wiki/
    └── custom/

Migration Report

After import, a detailed report is generated:

Location: .specweave/docs/internal/projects/{project}/legacy/README.md

Contents:

Import summary (counts per category)
Classification analysis (with confidence scores)
List of imported files
Next steps and recommendations

Configuration Updates

Import history is tracked in .specweave/config.json:

{
  "brownfield": {
    "importHistory": [{
      "source": "notion",
      "workspace": "acme-corp",
      "importedAt": "2025-11-06T10:30:00Z",
      "project": "web-app",
      "filesImported": 47,
      "destination": ".specweave/docs/internal/projects/web-app/legacy/notion/"
    }]
  }
}

After Import

Review classification - Check migration report
Move misclassified files - Use file manager or git
Update spec numbers - Rename to spec-NNN-name.md
Clean up legacy - Delete obsolete content
Update references - Fix broken links

When to Use

Migrating from Notion to SpecWeave
Consolidating wikis from GitHub, Confluence, etc.
Onboarding brownfield projects with existing documentation
Merging multiple doc sources into single SpecWeave instance

Limitations

Only markdown files (.md, .markdown) supported
No direct API integration (use exports)
Classification is heuristic (80%+ accuracy target)
Manual review recommended for low-confidence files

/import-docs