docalign-setup

name	docalign-setup
description	Interactive setup wizard for DocAlign. Guides user through: doc discovery → selection → configuration → document annotation → initial scan. Safe to re-run after partial completion — already-processed documents are skipped. After setup fully 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:

1. Does .docalign/.setup-complete exist?

   • IF YES: Setup fully complete. Do nothing (docalign skill will handle usage).

2. Otherwise (no .setup-complete, regardless of whether config.yml exists):

   • If .docalign/config.yml exists, tell the user:

     Found a partial DocAlign setup. Re-running full setup — already-processed documents will be skipped in Phase 3.
     

   • Run ALL 4 phases in order: Phase 1 → Phase 2 → Phase 3 → Phase 4.
   • Do NOT skip Phase 1 or Phase 2. Always ask the user which docs to monitor.
   • The only optimization is in Phase 3: sub-agents skip docs that already have a semantic JSON file.

---

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. Run targeted globs first (these must never be missed), then the broad sweep:

   • docs/**/*.md and docs/**/*.mdx — always run explicitly
   • README.md, CONTRIBUTING.md, CHANGELOG.md — root-level standalones
   • **/*.md and **/*.mdx — broad sweep to catch everything else

   Why targeted first: the broad glob returns at most 100 results and truncates on large repos. Running docs/**/*.md explicitly guarantees the docs/ directory is always fully represented even when the broad glob is cut off.

   Deduplicate results across all glob calls. Exclude from all results: 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?

Wait for user confirmation, then proceed immediately.

---

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: Ask to Write Document Headers

Before writing any headers, ask:

📎 Optional: YAML frontmatter headers

I can add a small metadata block to the top of each monitored document:

  ---
  title: "Getting Started"
  summary: "Walks new users through installation and first run."
  category: guide
  read_when:
    - Setting up the project for the first time
    - Troubleshooting installation issues
  related:
    - docs/reference/cli.md
  docalign:
    monitored: true
  ---

This is entirely optional. It helps AI agents (and humans) quickly
understand what each doc is for and when to read it — without opening
the file. It does not affect how drift detection works.

Add YAML headers to your docs? [yes / no]

IF user says yes: write headers to all selected documents using the process below.

IF user says no: skip this step entirely and proceed to Step 2.3.

Header writing process (when approved):

For EACH selected document, 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 (adapt based on whether headers were written):

✅ Configuration saved to .docalign/config.yml
✅ Headers written to 8 documents   ← omit this line if user declined headers

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

---

Phase 3: Document Processing (Parallel Sub-Agents)

Step 3.1: Ask user for concurrency limit

Before doing anything else, tell the user how many documents need processing and ask:

Ready to process {N} documents. Each document is handled by a parallel sub-agent.

How many sub-agents should run at once?

[1] Conservative — 3 at a time  (slow but light on RAM/CPU)
[2] Balanced    — 5 at a time  (recommended for most machines)
[3] Fast        — 10 at a time (good if you have 16 GB+ RAM)
[4] Custom      — enter a number

Running too many in parallel can exhaust memory on large repos.

Use the user's answer as the batch size for Step 3.3. If the user picks Custom, accept any integer between 1 and 20. Default to 5 if the user skips the question.

Step 3.2: Prepare context, then spawn sub-agents

Before spawning, do this once:

1. Read the sub-agent spec. Check these locations in order and use the first that exists:
   • .claude/skills/docalign-setup/document-processor.md (project-level, installed by docalign init)
   • ~/.claude/skills/docalign-setup/document-processor.md (user-level, installed by docalign init)
   • skills/docalign-setup/document-processor.md (repo-relative fallback for docalign dev repo)
2. Create the output directory so sub-agents don't race to create it:

   mkdir -p .docalign/semantic
   

3. Filter already-processed documents. List existing .json files in .docalign/semantic/. For each selected document, compute its expected JSON filename (replace / with --, append .json). If the JSON file exists and is non-empty, that document was already fully processed — remove it from the list. Report to the user:

   Found {N} already-processed documents — skipping those.
   Remaining: {M} documents to process.
   

   If ALL documents are already processed, skip directly to Phase 4.

Then spawn one Task sub-agent per remaining 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_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.3: Batched Parallel Execution

Split the document list into batches of the chosen size. For each batch:

1. Spawn all agents in the batch in a single message (parallel)
2. Wait for all of them to finish before starting the next batch
3. After each batch, report progress using this format:

━━━ Batch 2/4 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✅ docs/api.md                 14 claims extracted
  ✅ docs/setup.md                8 claims extracted
  ✅ docs/architecture.md        11 claims extracted
  ⏭️  docs/guides/mcp.md          already processed

  Progress: ██████████░░░░░░░░░░ 10/19 docs

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use ✅ for successful, ⏭️ for skipped (already processed), ❌ for failed. Build the progress bar proportionally: each █ = 5% done, each ░ = 5% remaining (20 chars total).

Step 3.4: 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.5: Collect Results

As sub-agents complete, parse each sub-agent's report to extract: claim counts by type, evidence counts, skip region counts. Aggregate across all documents.

Present the final summary using this format:

┌─────────────────────────────────────────────────────┐
│           📋 Document Processing Complete            │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Documents             19 total                     │
│    ✅ Processed:       17                           │
│    ⏭️  Skipped:         2  (already done)           │
│    ❌ Failed:           0                           │
│                                                     │
│  Claims Extracted     150 total                     │
│    🔍 behavior          87                          │
│    🏗️  architecture      34                          │
│    ⚙️  config            29                          │
│                                                     │
│  Evidence                                           │
│    ✅ With evidence:  132  (88%)                    │
│    ⚠️  No evidence:    18  (12%) — likely drifted   │
│                                                     │
│  Skip Regions          45 illustrative blocks       │
│                        tagged across all docs       │
│                                                     │
└─────────────────────────────────────────────────────┘

Fill in real numbers from the sub-agent reports. Adjust column widths to fit actual data. If any documents failed, list them under the ❌ line.

---

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", deep=true

Present results using this format (fill in real data from the tool response):

┌─────────────────────────────────────────────────────┐
│          📊 README.md — Health Check                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Health Score  ████████████████░░░░  80/100          │
│                                                     │
│  Claims: 15 total                                   │
│    ✅ Verified:   12  (80%)                         │
│    ⚠️  Drifted:     2  (13%)                        │
│    ❓ Uncertain:   1  ( 7%)                         │
│                                                     │
├─── Drifted Claims ──────────────────────────────────┤
│                                                     │
│  Line 23 │ Path "src/auth.ts" not found             │
│          │ 💡 Did you mean src/authentication.ts?   │
│          │                                          │
│  Line 45 │ Script "npm run deploy" not in           │
│          │ package.json                              │
│          │ 💡 Add script or update docs             │
│                                                     │
└─────────────────────────────────────────────────────┘

Build the health score bar proportionally: each █ = 5%, 20 chars total. Use real line numbers and claim text from the check_doc response. Only show the drifted claims section if there are drifted claims.

IF user chooses 2 (Fast Scan):

Running full scan on all selected docs...

For each doc, call check_doc and aggregate results. Present using this format:

┌─────────────────────────────────────────────────────┐
│          📊 Documentation Health Report             │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Overall Health  ████████████████░░░░  87/100       │
│                                                     │
│  Document                Claims   Verified  Status  │
│  ───────────────────────────────────────────────    │
│  README.md                  15      93%       ✅    │
│  docs/api.md                42      88%       ✅    │
│  docs/architecture.md       31      97%       ✅    │
│  docs/setup.md              23      78%       ⚠️    │
│  docs/config.md             18     100%       ✅    │
│                                                     │
├─── Top Issues (up to 5) ────────────────────────────┤
│                                                     │
│  1. docs/setup.md:34                                │
│     ⚠️  Command "npm run deploy" — script not found │
│                                                     │
│  2. docs/api.md:128                                 │
│     ⚠️  Parameter "userId" — not in signature      │
│                                                     │
│  3. docs/setup.md:56                                │
│     ⚠️  Version "3.2.1" — package.json has "4.0.0" │
│                                                     │
└─────────────────────────────────────────────────────┘

Sort the document table by verified % ascending (worst first). Use ✅ for ≥85% verified, ⚠️ for <85%. Show up to 5 top issues, prioritizing drifted claims. If all docs are 100% verified, replace the "Top Issues" section with: "🎉 No issues found — all documentation is in sync!"

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: Write Completion Marker

Write the file .docalign/.setup-complete with the current ISO timestamp. This marker signals that setup finished successfully and prevents the wizard from re-triggering.

date -u +"%Y-%m-%dT%H:%M:%SZ" > .docalign/.setup-complete

Step 4.5: Final Summary

Present the final summary using this format (fill in real numbers):

┌─────────────────────────────────────────────────────┐
│             ✅ DocAlign Setup Complete!              │
├─────────────────────────────────────────────────────┤
│                                                     │
│  What was created                                   │
│    📄 Config       .docalign/config.yml             │
│    📚 Monitored    19 documentation files           │
│    🔍 Claims       150 semantic claims indexed      │
│    📁 Store        .docalign/semantic/              │
│                                                     │
│  What happens next                                  │
│    After you edit code, I'll suggest checking        │
│    related docs for drift. You can also run:        │
│                                                     │
│    docalign scan    check all docs                  │
│    docalign check   verify a single file            │
│    docalign fix     apply suggested corrections     │
│                                                     │
│  The docalign skill is now active. 🚀              │
│                                                     │
└─────────────────────────────────────────────────────┘

---

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. .docalign/.setup-complete marker written (prevents wizard from re-triggering)
3. This skill becomes inactive (trigger condition no longer met)
4. User restarts Claude Code
5. docalign skill (daily usage) becomes active
6. 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