---
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 --yes docguard-cli@0.48.0)
metadata:
  author: docguard
  version: 0.48.0
  source: extensions/spec-kit-docguard/skills/docguard-fix
---
<!-- docguard:version: 0.48.0 -->

# DocGuard Fix Skill

## Running DocGuard

Run `docguard` from PATH when it is installed. Otherwise run
`npx --yes docguard-cli@0.48.0`, the release these instructions ship with, in its
place. Every `docguard …` command below means one of the two.

## User Input

```text
$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 configurable 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

## Scope: `act` findings only

Read `disposition` from `docguard guard --format json` before repairing anything.

- **`act`** — DocGuard asserts a defect and names the correction. In scope.
- **`escalate`** — DocGuard observed a signal and the judgement belongs to a human (freshness history, diff-overlap suspicion, documented-endpoint absence). **Out of scope for this skill.** Report them for review; never edit a document to silence one. A history heuristic saying a review is DUE is not evidence that the document is wrong, and stamping a new review date to clear it destroys the signal without doing the review.

Also read `parserTier`: a finding produced by `regex-fallback` or `fallback-language` came from a pattern match rather than a syntax tree, so verify the underlying source before rewriting a document around it.

## Execution Flow

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

```bash
docguard 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` whole documents. Mapped human docs expose only unique
`source=code` sections, and `--force` cannot bypass ownership. The operation is
idempotent and prints what changed. Don't hand-edit generated sections.

### Step 1: Diagnose Current State

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

```bash
docguard 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**:
   ```markdown
   # [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:
<!-- docguard:authoring-contract — generated by `npm run docs:reference` from cli/authoring-contract.mjs; edit the registry, not this block -->
   - **ARCHITECTURE.md**: System Overview, Component Map, Tech Stack; recommended: Layer Boundaries, Data Flow
   - **DATA-MODEL.md**: Entities (when the project has a database); recommended: Relationships, Indexes
   - **SECURITY.md**: Authentication, Secrets Management; recommended: Authorization, Security Boundaries
   - **TEST-SPEC.md**: Test Categories, Coverage Rules; recommended: Test Commands
   - **ENVIRONMENT.md**: Environment Variables (when the code reads any), Setup Steps; recommended: Configuration Files
<!-- /docguard:authoring-contract -->
   - **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**:
   ```bash
   docguard 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:

```markdown
## 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 the `docguard-guard` skill 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

## Evidence Findings

Run `docguard verify --evidence --format json` when guard returns an `EVD` code.
Repair invalid, missing, ambiguous, stale, or unsupported evidence at the named
source. For `EVD002`, inspect the approved requirement and implementation before
editing either side; current code does not automatically override canonical
intent. Rerun evidence verification after the targeted change. Never broaden a
statement template or remove an evidence declaration merely to make guard pass.

## 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

## When DocGuard says it is old

If DocGuard's output says its version was released more than 14 days ago, tell
the user and offer to run `docguard upgrade`, which checks npm for a newer
version only when it runs. Never upgrade DocGuard without the user's agreement,
and never treat the note as a failure: it says a newer version may exist, not
that one does.

## Context

$ARGUMENTS
