docalign-setup

name	docalign-setup
description	Interactive setup wizard for DocAlign. USE ONLY when .docalign/config.yml does not exist. Guides user through: doc discovery → selection → configuration → document annotation → initial scan. After setup completes, this skill becomes inactive and docalign skill takes over.
metadata	{"author":"DocAlign","version":"0.3.0","trigger":"config_missing"}

DocAlign Interactive Setup

Auto-Trigger Condition

CHECK IMMEDIATELY ON LOAD: Does .docalign/config.yml exist?

• IF NO: This is first-time setup. Begin "Setup Wizard" workflow below.
• IF YES: Setup already complete. Do nothing (docalign skill will handle usage).

---

Setup Wizard (4 Phases)

Phase 1: Discovery & Document Selection

Step 1.1: Welcome & Discovery

Say to user:

👋 Welcome to DocAlign!

I can help you keep documentation in sync with your code. Let me start by
discovering what documentation you have in this project.

Scanning for documentation files...

Step 1.2: Discover Documentation

1. Use Glob tool to find all markdown files:

   • **/*.md
   • **/*.mdx
   • Exclude: node_modules/, .git/, dist/, build/

2. Categorize each doc:

   • Core docs: README.md, docs/*/.md, API docs
   • Changelog: CHANGELOG.md, HISTORY.md, NEWS.md
   • Backlog/Planning: tasks/, backlog/, planning/**
   • Legacy: docs/legacy/, docs/archive/
   • Examples: examples/, tutorials/

3. Calculate token estimates:

   • Read first 100 lines of each core doc to estimate size
   • Rough formula: 1 token ≈ 4 characters
   • Group by category

Step 1.3: Present Interactive Selection

Use interactive UI to present multi-select:

📚 Documentation Discovery Complete

Found 12 documentation files:

┌─ Core Documentation (Recommended) ─┐
│ [✓] README.md                 500 tokens  │
│ [✓] docs/api.md              1200 tokens  │
│ [✓] docs/setup.md             800 tokens  │
│ [✓] docs/architecture.md     1500 tokens  │
└──────────────────────────────────────────┘

┌─ Auto-Generated (Usually Skip) ────────┐
│ [✗] CHANGELOG.md              300 tokens  │
│ [✗] LICENSE.md                200 tokens  │
└──────────────────────────────────────────┘

┌─ Internal/Planning (Usually Skip) ─────┐
│ [✗] tasks/backlog.md          400 tokens  │
│ [✗] planning/roadmap.md       600 tokens  │
└──────────────────────────────────────────┘

┌─ Legacy/Archive ───────────────────────┐
│ [?] docs/legacy/v1-api.md    1000 tokens  │
└──────────────────────────────────────────┘

Estimated tokens for initial scan: ~5,000

[Actions]
• Click to toggle selection
• "all" - monitor all docs
• "core" - monitor only core docs
• "done" - confirm selection

Step 1.4: Handle User Input

• User clicks/toggles individual docs
• Or types: "all", "core", "skip 3,7", "done"
• Validate: at least 1 doc selected
• Show updated token estimate

Step 1.5: Confirm Selection

Say:

✅ Selection confirmed:
• Monitoring: 8 docs (~5,000 tokens)
• Skipping: 4 docs (changelog, internal)

Ready to proceed to configuration?

---

Phase 2: Configuration & Headers

Step 2.1: Generate Configuration

1. Create .docalign/config.yml:

# DocAlign Configuration
# Generated by interactive setup

doc_patterns:
  include:
    # Core documentation (user selected)
    - README.md
    - docs/**/*.md
    - [other selected docs...]

  exclude:
    # Auto-generated files
    - CHANGELOG.md
    - CHANGELOG-*.md
    - HISTORY.md
    - NEWS.md
    - LICENSE.md

    # Internal planning
    - tasks/**
    - backlog/**
    - planning/**

    # Build artifacts
    - node_modules/**
    - dist/**
    - build/**

code_patterns:
  include:
    - "**"
  exclude:
    - node_modules/**
    - .git/**
    - dist/**
    - build/**
    - coverage/**

verification:
  min_severity: low
  max_claims_per_pr: 50

llm:
  verification_model: claude-sonnet-4-20250514
  extraction_model: claude-sonnet-4-20250514

2. Write config file using Write tool

Step 2.2: Write Document Headers

For EACH selected document, write YAML frontmatter header:

Read the document first to understand its content, then write:

---
title: "[Extracted from doc]"
summary: "[2-3 sentence summary of purpose]"
description: "[Detailed description of what this doc covers]"
category: "[tutorial|reference|api|architecture|guide]"
read_when:
  - [Specific scenario when user should read this]
  - [Another scenario]
related:
  - [relative/path/to/related-doc.md]
  - [another/related/doc.md]
docalign:
  setup_date: "2024-01-15T10:30:00Z"
  monitored: true
---

[Original document content follows...]

Process per doc:

1. Read existing content
2. Analyze: What is this doc about?
3. Extract/generate metadata (title, summary, category)
4. Identify related docs (files that reference each other)
5. Write header + original content back

Step 2.3: Report Progress

Say:

✅ Configuration saved to .docalign/config.yml
✅ Headers written to 8 documents

Next: Processing documents to extract claims and add annotations...

---

Phase 3: Document Processing (Parallel Sub-Agents)

Step 3.1: Prepare context, then spawn sub-agents

Before spawning, do this once:

1. Read the sub-agent spec: skills/docalign-setup/document-processor.md
2. Create the output directory so sub-agents don't race to create it:

   mkdir -p .docalign/semantic
   

Then spawn one Task sub-agent per document. Use the context you already have from Phase 2 (you read each document when writing its YAML header) to populate the dynamic context block:

Read the Document Processor spec at: {absolute_path_to_repo}/skills/docalign-setup/document-processor.md

Then process this document according to that spec.

Document: {file_path}
Repository root: {absolute_repo_root}

--- Dynamic context ---
{Add what you observed from briefly scanning the document, e.g.:}
- Source directories referenced in this doc: src/layers/L1-claim-extractor/, src/cli/
- Specific files mentioned: src/cli/real-pipeline.ts, package.json
- Package manager: npm
- Primary language: TypeScript (strict)
- Any other notes relevant to finding evidence for claims in this doc

2. Please ensure that the dynamic context you provide to each sub-agent is complete, relevant, and self-contained to provide the subagent with sufficient information to perform its task correctly.

Step 3.2: Parallel Execution

• Spawn ALL sub-agents in parallel
• Track progress: "Processing 5/8 documents..."

Step 3.3: Retry Logic

IF a sub-agent fails:

1. Log the failure
2. Wait 2 seconds
3. Retry the same sub-agent (up to 3 attempts)
4. If still failing after 3 retries:
   • Mark doc as "failed"
   • Continue with other docs
   • Report to user at end

Step 3.4: Collect Results

As sub-agents complete:

• Count successful completions
• Collect summaries
• Track any failures

Say:

✅ Document processing complete:
• Successful: 7 docs
• Failed: 1 doc (docs/legacy/api.md)
• Claims extracted: ~150 total
• Tags written: ~200 total

---

Phase 4: Initial Scan

Step 4.1: Offer Initial Scan

Say:

🎉 Setup nearly complete!

Your documentation is now configured and annotated. Let's verify everything
is working with an initial scan.

Choose scan scope:

[1] Quick Demo - Check README only (~30 seconds)
    Great for seeing how results look

[2] Fast Scan - Check all selected docs (~2 minutes)
    Full verification of your documentation

[3] Skip for now - Complete setup, scan later
    You can run "docalign scan" anytime

Enter 1, 2, or 3:

Step 4.2: Execute Scan

IF user chooses 1 (Quick Demo):

Running quick check on README.md...

Call MCP tool: check_doc with file="README.md"

Present results:

📊 README.md Check Results:

Claims found: 15
✅ Verified: 12 (80%)
⚠️  Drifted: 2 (13%)
❓ Uncertain: 1 (7%)

Drifted Claims:
• Line 23: Path "src/auth.ts" doesn't exist
  Suggested fix: "src/authentication.ts"

• Line 45: Command "npm run deploy" script not found
  Suggested fix: Add to package.json or update docs

Overall health: Good! Most docs are accurate.

IF user chooses 2 (Fast Scan):

Running full scan on all selected docs...
This will take approximately 2 minutes.

For each doc, call check_doc and aggregate results:

📊 Documentation Health Report

Overall Score: 87/100

✅ README.md        15 claims  (93% verified)
✅ docs/api.md      42 claims  (88% verified)
⚠️  docs/setup.md   23 claims  (78% verified)
   └─ 3 drifted claims found

Top Issues:
1. docs/setup.md line 34: Outdated command
2. docs/api.md line 128: Missing parameter
3. docs/setup.md line 56: Wrong version

Step 4.3: Clean Up Setup Trigger

Remove the auto-trigger notice from CLAUDE.md:

1. Read CLAUDE.md from the project root
2. Remove the block between <!-- docalign:setup-pending --> and <!-- /docalign:setup-pending --> (inclusive, including the trailing blank line)
3. Write the updated content back
4. If CLAUDE.md is now empty, delete it

Step 4.4: Final Summary

Say:

✅ DocAlign Setup Complete!

Configuration:
• Config file: .docalign/config.yml
• Monitored docs: 8 files
• Semantic claims: .docalign/semantic/

Next Steps:
• Run "docalign scan" anytime to check all docs
• After code changes, I'll suggest checking related docs
• Use "docalign fix" to apply suggested fixes

The docalign skill is now active for daily usage.

---

Error Handling

Document Processing Failures

IF sub-agent fails:

1. First failure: Retry immediately
2. Second failure: Wait 2 seconds, retry
3. Third failure:
   • Mark as permanent failure
   • Add to .docalign/failed-docs.json
   • Continue with other docs
   • Report at end: "1 doc failed processing (will retry on next scan)"

User Cancellation

IF user cancels during setup:

1. Stop current operation gracefully
2. Save partial progress to .docalign/config.yml
3. Say: "Setup paused. Run 'docalign init' to continue."

Missing Tools

IF MCP tools unavailable:

Say:

⚠️  DocAlign MCP server not connected.

Please ensure:
1. DocAlign is installed: npm install -g docalign
2. Run: docalign init (to configure MCP)
3. Restart Claude Code

---

Post-Setup Transition

After setup completes successfully:

1. .docalign/config.yml now exists
2. This skill becomes inactive (trigger condition no longer met)
3. User restarts Claude Code
4. docalign skill (daily usage) becomes active
5. Normal workflows begin (post-change checks, health monitoring, etc.)

---

Key Design Principles

1. Transparent: User sees every step, understands what's happening
2. Educational: Explains token costs, claim types, why certain docs are skipped
3. Forgiving: Retry logic, can resume if interrupted
4. Progressive: Demo option lets user see value before full scan
5. Parallel: Sub-agents process docs simultaneously for speed