Import Docs

Import Brownfield Documentation

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

What This Does

1. Analyzes markdown files in source directory (recursively)
2. 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)
3. Copies files to appropriate destinations
4. Creates migration report with classification details
5. 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

1. Review classification - Check migration report
2. Move misclassified files - Use file manager or git
3. Update spec numbers - Rename to spec-NNN-name.md
4. Clean up legacy - Delete obsolete content
5. 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

See Also

• /sw:init-multiproject - Set up multi-project mode first
• Brownfield Import Guide
• Migration Best Practices

Implementation: src/cli/commands/import-docs.ts