docguard-fix

name	docguard-fix
description	AI-driven documentation repair with structured research workflow, template-aware generation, and quality validation loops. Generates or fixes canonical documentation by researching the actual codebase, not using placeholders. Iterates until guard passes.
compatibility	Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
metadata	{"author":"docguard","version":"0.33.1","source":"extensions/spec-kit-docguard/skills/docguard-fix"}

DocGuard Fix Skill

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty). If user specifies --doc <name>, focus on that single document. If no arguments, fix ALL issues found by docguard diagnose.

Goal

Research the actual codebase to generate or repair canonical documentation that passes DocGuard's 19-validator guard suite. This skill replaces generic templates with real, project-specific content and iterates until quality checks pass.

Operating Constraints

• NEVER use placeholder content — every section must reference real files, real modules, real dependencies
• ALWAYS back up before overwriting — use safeWrite() pattern or create .bak files
• Maximum 3 validation iterations — if still failing after 3 rounds, report remaining issues and stop
• Research before writing — understand the codebase first, then generate documentation

Execution Flow

Step 0: Apply Mechanical Fixes First (no AI needed)

npx docguard-cli fix --write 2>&1

Removes endpoints documented in docs-canonical/API-REFERENCE.md that the OpenAPI spec confirms no longer exist (table row + detail block). Only edits docguard:generated docs, idempotent, prints what changed. Don't hand-edit these.

Step 1: Diagnose Current State

Run the diagnostic to identify all issues (each tagged mechanical or agent):

npx docguard-cli diagnose 2>&1

Parse the output to build an issue inventory:

Issue ID	Severity	Category	File	Description	Autofix?
I001	ERROR	Structure	SECURITY.md	Missing file	Yes
I002	WARN	Freshness	ARCHITECTURE.md	5 commits behind	Yes
...	...	...	...	...	...

If $ARGUMENTS contains --doc <name>, filter to only issues affecting that document.

Step 2: Prioritize Fix Order

Sort issues by fix dependency and impact:

1. Structure first (missing files must exist before checking sections)
2. Doc Sections second (sections must exist before checking quality)
3. Doc-Quality third (readability and language improvements)
4. Freshness fourth (update last-reviewed dates)
5. Metadata-Sync fifth (ensure headers are consistent)
6. Everything else last

Step 3: Research the Codebase (Per Document)

For each document that needs fixing, execute a targeted research pass. Research must be thorough — read actual code, not just filenames.

For ARCHITECTURE.md:

1. Read package.json for project name, description, dependencies, scripts
2. List top-level directory structure (ls -la, focus on src/, lib/, cli/, app/)
3. Identify entry points — check main, bin, exports in package.json
4. For each major directory, read 2-3 representative files to understand purpose
5. Map the import graph — which modules import which
6. Identify external dependencies and their roles

For SECURITY.md:

1. Check .gitignore for security-related patterns (.env, secrets, keys)
2. Search for auth patterns: grep -r "auth\|token\|jwt\|session\|password\|secret" src/ lib/ --include="*.js" --include="*.mjs"
3. Check package.json for auth dependencies (passport, jwt, bcrypt)
4. Look for middleware, guards, or permission checks
5. Check for .env files (document variable names only, NEVER values)
6. Look for CORS, rate limiting, input validation

For TEST-SPEC.md:

1. Read package.json scripts for test commands
2. Find test files: find . -name "*.test.*" -o -name "*.spec.*" | head -20
3. Read test configuration (jest.config, vitest.config, etc.)
4. Read 2-3 test files to understand patterns
5. Check for E2E setup (playwright, cypress)
6. Look for CI config that runs tests

For DATA-MODEL.md:

1. Search for schema definitions: grep -r "Schema\|model\|Table\|Entity\|interface\|type " src/ lib/
2. Check for ORM configs (prisma, sequelize, mongoose, drizzle)
3. Look for migration files
4. Check for TypeScript interfaces/types defining data shapes
5. Look for Zod schemas, JSON schemas, validation files
6. If no database: document config file formats

For ENVIRONMENT.md:

1. Read package.json for engines, scripts, dependencies
2. Check for .nvmrc, .node-version, .tool-versions
3. Search for process.env usage: grep -r "process.env" src/ lib/ cli/
4. Check for .env.example or .env.template
5. Check for Docker/docker-compose files
6. Look for setup scripts

Step 4: Generate or Fix Document Content

For each document, follow this strict writing protocol:

1. Load the metadata header template:

   # [Document Title]
   
   <!-- docguard:version X.X.X -->
   <!-- docguard:status active -->
   <!-- docguard:last-reviewed YYYY-MM-DD -->
   

2. Write each mandatory section using research findings:

   • Use actual file paths, module names, and dependency names
   • Use markdown tables for structured data (fields, types, constraints)
   • Use code blocks for command examples (with actual working commands)
   • Keep language positive (avoid negation — "MUST use" not "MUST NOT avoid")
   • Write at Flesch-Kincaid grade level 8-10 (clear, professional, not academic)

3. Validate mandatory sections exist. Each canonical doc requires:

   • ARCHITECTURE.md: System Overview, Component Map, Layer Boundaries, Data Flow, Technology Choices
   • SECURITY.md: Auth Mechanism, Secrets Inventory, Secrets Storage, Permissions, Security Boundaries
   • TEST-SPEC.md: Test Framework, Test Structure, Test Commands, Critical Flows, Coverage
   • DATA-MODEL.md: Data Structures/Schemas, Field Types/Constraints, Relationships, Indexes
   • ENVIRONMENT.md: Prerequisites, Setup Steps, Environment Variables
   • REQUIREMENTS.md: Functional Requirements (FR-IDs), Non-Functional Requirements

4. Apply DocGuard quality rules:

   • Section count ≥ 3 per document
   • No TODO/placeholder text in final output
   • Positive language (IEEE 830 §4.3 compliance)
   • Each section has substantive content (not just a heading)

Step 5: Format Compliance

Ensure every generated document follows CDD format rules:

• Metadata header: Must include docguard:version, docguard:status, docguard:last-reviewed
• Heading hierarchy: Single # H1, then ## H2 sections, then ### H3 subsections
• Tables: Use markdown tables for structured data (pipes aligned, header separators with 3+ dashes)
• Code blocks: Use fenced blocks with language identifier for all commands/code
• Line length: Keep lines under 120 characters for readability
• No trailing whitespace

Step 6: Validation Loop (Max 3 Iterations)

After writing/fixing each document:

1. Run guard on the specific validator:

   npx docguard-cli guard 2>&1
   

2. Parse results for the affected validators

3. If still failing:

   • Identify exactly which checks are still failing
   • Apply targeted fixes (not a full rewrite)
   • Re-run guard

4. If passing after iteration: Move to next document

5. If still failing after 3 iterations: Report remaining issues with specific error details

Step 7: Completion Report

After all fixes are applied, output:

## DocGuard Fix Report

### Documents Fixed
| Document | Action | Checks Before | Checks After | Status |
|----------|--------|:------------:|:------------:|--------|
| SECURITY.md | Created | 0/2 | 2/2 | ✅ |
| ARCHITECTURE.md | Updated sections | 6/8 | 8/8 | ✅ |

### Guard Score
- **Before**: [X]/[Y] checks passed
- **After**: [X]/[Y] checks passed
- **Improvement**: +[N] checks

### Remaining Issues (if any)
- [Issue description] — [Why it couldn't be auto-fixed]

### Suggested Next Steps
- Run `/docguard.guard` to verify full compliance
- Review generated content for accuracy
- Commit with: `docs: fix CDD documentation [list of docs fixed]`

Behavior Rules

• Research FIRST, write SECOND — never generate content without reading the codebase
• Be specific to THIS project — don't add generic boilerplate for features the project doesn't have
• Back up before overwriting — if file exists, create .bak first or use safeWrite()
• Respect existing content — when updating, preserve user-written sections and only add/fix missing parts
• Log deviations — if you deviate from canonical expectations, add // DRIFT: reason in DRIFT-LOG.md
• Never include secrets — document variable/secret NAMES only, never actual values

Integration with Spec Kit

If .specify/ directory exists:

• Check constitution.md for project principles before generating docs
• Align documentation language with constitutional requirements
• If specs/*/spec.md exists, cross-reference requirements with TEST-SPEC.md

Context

$ARGUMENTS