Documentation Maintenance Guide

Rules and procedures for keeping Nquiry documentation accurate and current.

Companion doc: docs-voice-style-guide.md covers tone and word-choice differentiation across audiences (end-user, licensee, sales/prospect). This doc covers freshness, links, and structural hygiene. Use both when reviewing a doc.

Automation

A weekly scheduled Cowork task runs the checks below automatically and posts findings to a recurring Linear issue. You usually do not need to run the manual procedures in this doc — the automation does it for you. The procedures are documented anyway so anyone can run an ad-hoc check (e.g., right after a big restructure, or while preparing a release).

What	Where
Scheduled task	Created via Cowork's schedule skill — runs every Friday 09:00 ET
Spec	docs/working/nqu-633-phase5-scheduled-task-spec.md (until task is operational; then archive to git history)
Recurring report issue	NQU-670 — "Weekly Documentation Freshness Report"
Output cadence	Linear comment per run; "🟢 green" comment even on no-findings weeks (silence is ambiguous)
Scope (v1)	investigation-app only — docs/guide/, docs/admin/, docs/reference/, plus expired-Expires: sweep over docs/working/

If the task posts a 🔴 (failure) report, run the relevant manual procedure below to triage, then have Cowork re-create the task if it's broken.

Freshness Model

Every documentation file in guide/, admin/, and reference/ uses frontmatter with a last-verified date. A document is considered:

• Fresh: last-verified within the last 90 days
• Stale: last-verified between 90 and 180 days ago
• Expired: last-verified more than 180 days ago

Single Source of Truth

docs/product-facts.md is the canonical reference for all product claims. When something changes:

1. Update product-facts.md first
2. Check the Propagation Checklist (end of product-facts.md) for downstream consumers
3. Update each downstream document
4. Bump the last-verified date in each updated file's frontmatter

Manual Procedures (ad-hoc use)

These are the same checks the scheduled task runs. Use them when you need an immediate answer (right after a restructure, before a release, debugging a 🔴 automation failure).

1. Check for Expired Working Docs

Scan docs/working/ for files past their Expires: date. Delete expired files (or extract durable content into guide//admin//reference/ first if they have lasting value).

# List Expires lines from working docs (visual scan)
grep -nH "^Expires:\|^\*\*Expires:\*\*" docs/working/*.md

2. Freshness Sweep

Find docs with last-verified older than 90 days. The check looks at the first last-verified: line per file (the one in frontmatter), so it ignores incidental occurrences inside code blocks or examples.

# Linux / Cowork sandbox (uses GNU date -d)
threshold=$(date -d '90 days ago' +%Y-%m-%d)
for f in $(find docs/guide docs/admin docs/reference -name "*.md"); do
  # Pull the frontmatter last-verified line only (first match)
  date=$(awk '/^---/{c++; next} c==1 && /^last-verified:/{gsub(/.*last-verified:[[:space:]]*"?/, ""); gsub(/"?[[:space:]]*(#.*)?$/, ""); print; exit}' "$f")
  if [ -z "$date" ]; then
    echo "MISSING_VERIFY: $f"
  elif [[ "$date" < "$threshold" ]]; then
    echo "STALE: $f — last verified $date"
  fi
done

# macOS (BSD date) — substitute this line for the threshold
threshold=$(date -v -90d +%Y-%m-%d)
# (or: threshold=$(python3 -c "import datetime; print((datetime.date.today() - datetime.timedelta(days=90)).isoformat())"))

For each stale doc: re-read the file, verify claims against product-facts.md and the code, update if needed, bump last-verified.

3. Stale Terminology Sweep

# Retired terms that should not appear in current docs
grep -rn 'Low Verifiability\|ten.*criteria\|\bContradicted\b' docs/guide/ docs/admin/ docs/reference/ --include="*.md"

# Codebase ID used as product name (regex word boundary, so nquir-landing/app.nquir.ai are not flagged)
grep -rnE '\bnquir\b' docs/guide/ docs/admin/ docs/reference/ --include="*.md" | grep -v 'nquir-landing\|app\.nquir\.ai\|nquir_business'

# Plan-name slips
grep -rn 'Professional\|\bTeam plan\b\|\bFREE\b' docs/guide/ docs/admin/ docs/reference/ --include="*.md"

# Trial detail drift (storage was 25GB by mistake; AI quota was 25 by mistake)
grep -rn 'Trial.*25 ?GB\|Trial.*25 AI\|25 AI gen' docs/guide/ docs/admin/ docs/reference/ --include="*.md"

False positive notes:

• "Low Verifiability" / "Contradicted" appearing inside an explicit "Legacy note:" or historical section is intentional. Spot-check before fixing.
• "Professional" / "Team" are the internal DB enum names — they may legitimately appear in reference/ docs that document the schema. Flag is a heads-up, not a mandate.

4. Cross-Reference Check (Broken Internal Links)

# Quick visual: list all .md links and the file they point at
grep -rnE '\[[^]]+\]\([^)]+\.md(#[^)]+)?\)' docs/guide/ docs/admin/ docs/reference/ --include="*.md"

For a programmatic check, use the scheduled task's link resolver — its logic is in docs/working/nqu-633-phase5-scheduled-task-spec.md §4 check 3.

Propagation Triggers

When these events happen, specific docs need updating:

Event	Update These Docs
Pricing change (lib/billing/plans.ts)	product-facts.md §11 → guide/features/billing.md, admin/enterprise-overview.md (dual-channel), admin/onboarding-guide.md (dual-channel), AI Guide (lib/ai/prompts.ts), FAQ (nquir-landing/content/faq-knowledge.md)
New analysis type	product-facts.md §5 → guide/workflow/analysis.md, reference/adding-analysis-types.md, reference/analysis-system-features.md
Auth changes	product-facts.md §13 → admin/authentication.md, admin/enterprise-overview.md, admin/security-questionnaire.md
New evidence type	product-facts.md §6 → guide/workflow/evidence-collection.md, FAQ
Security posture change	product-facts.md §13 → admin/enterprise-overview.md, admin/security-questionnaire.md, admin/customer-environment-requirements.md (encryption/IAM/network sections), admin/security/ docs
Workflow change	product-facts.md §4 → guide/workflow/ docs, AI Guide STATUS_GUIDANCE
Confidence level change	product-facts.md §10 → guide/features/quality-metrics.md, AI Guide APP_FEATURES_REFERENCE, FAQ
Deployment-model / channel posture change	admin/enterprise-overview.md, admin/onboarding-guide.md, admin/security-questionnaire.md, admin/customer-environment-requirements.md, docs/decisions/2026-04-21-single-tenant-architecture.md, landing page (when SaaS↔licensed messaging shifts)

Frontmatter Standard

All documentation files in guide/, admin/, and reference/ must include:

---
audience: [end-user | enterprise | IT | compliance | developer | CC | CD]
owner: [CD | CC | Joe]
last-verified: YYYY-MM-DD
derived-from: product-facts.md # if claims derive from canonical reference
refresh-trigger: [optional — what events should trigger a re-check]
---

Audience Definitions

Audience Tag	Who	What They Need
end-user	Investigators, auditors, compliance officers	How to use Nquiry effectively
enterprise	IT admins, procurement evaluators	Architecture, security, deployment, pricing
IT	System administrators	Setup, configuration, user management
compliance	DPOs, HIPAA officers, auditors	Data handling, privacy, regulatory compliance
developer	CC, external contributors	Codebase conventions, APIs, schema
CC	Claude Code CLI	Automated agent context
CD	Claude Desktop / Cowork	Spec writing, documentation, research

Working Directory Rules

docs/working/ is for temporary files only. Every file must have an Expires: line at the top. The weekly maintenance sweep flags expired files for review (the task does not delete files — humans decide). If a working doc produces lasting value, extract the durable content into a permanent doc in guide/, admin/, or reference/ before the expiry date.