documentation-audit

name	documentation-audit
enabled	true
description	Use when performing documentation audit — audits the state of technical documentation across an engineering organization. Covers documentation inventory, freshness assessment, gap identification, quality scoring, ownership assignment, and a remediation plan to achieve comprehensive, accurate, and maintainable documentation.
required_connections	[{"prefix":"wiki","label":"Documentation Platform"}]
config_fields	[{"key":"documentation_platform","label":"Documentation Platform","required":true,"placeholder":"e.g., Confluence, Notion, GitBook, README files"},{"key":"scope","label":"Audit Scope","required":true,"placeholder":"e.g., all engineering docs, backend team, platform services"},{"key":"doc_count_estimate","label":"Estimated Number of Documents","required":false,"placeholder":"e.g., 200"}]
features	["TEAM_PRODUCTIVITY","DOCUMENTATION","AUDIT"]

Documentation Audit

Phase 1: Documentation Inventory

1. Catalog all existing documentation
   • Architecture documents and diagrams
   • API documentation
   • Runbooks and operational procedures
   • Onboarding guides
   • Service READMEs
   • Decision records (ADRs)
   • Postmortem/incident reports
   • How-to guides and tutorials
   • Configuration references
   • Troubleshooting guides
2. Record metadata for each document (owner, last updated, location)
3. Identify documentation scattered across multiple platforms

Documentation Inventory Summary

Category	Expected	Exists	Up-to-Date	Has Owner	Quality Score
Architecture					/5
API docs					/5
Runbooks					/5
Onboarding					/5
Service READMEs					/5
ADRs					/5
How-to guides					/5

Phase 2: Freshness Assessment

1. Evaluate documentation freshness
   • Last modified date for each document
   • Correlation with code/infrastructure changes since last update
   • Known inaccuracies flagged by team members
   • References to deprecated tools, services, or processes
2. Classify documents by freshness

Freshness Classification

Status	Criteria	Document Count	Percentage
Current	Updated within 6 months, matches reality		%
Stale	Updated 6-12 months ago, likely outdated		%
Obsolete	Updated 12+ months ago or references deprecated items		%
Missing	Expected documentation that does not exist		%

Phase 3: Gap Analysis

1. Identify documentation gaps
   • Services without README or architecture doc
   • Operations without runbooks
   • APIs without reference documentation
   • No onboarding guide for new team members
   • Missing decision records for key architectural choices
   • No troubleshooting guides for common issues
   • Missing disaster recovery procedures
2. Prioritize gaps by impact

Critical Gaps

Gap	Category	Impact	Affected Teams	Priority	Effort to Create
		High/Med/Low		1-5	Hours/Days

Phase 4: Quality Assessment

1. Score documents on quality dimensions
   • Accuracy: content matches current reality
   • Completeness: covers the topic adequately
   • Clarity: easy to understand for target audience
   • Findability: easy to discover and well-organized
   • Actionability: reader can follow steps successfully
   • Maintainability: easy to update when things change
2. Identify common quality issues

Quality Scoring Rubric

Dimension	1 (Poor)	3 (Adequate)	5 (Excellent)
Accuracy	Contains errors	Mostly correct	Verified accurate
Completeness	Major gaps	Covers basics	Comprehensive
Clarity	Confusing	Understandable	Clear with examples
Findability	Hard to find	Searchable	Well-organized, linked
Actionability	Cannot follow	Can follow with effort	Step-by-step with validation
Maintainability	Hard to update	Moderate effort	Template-based, modular

Phase 5: Ownership Assignment

1. Assign ownership for all documentation
   • Every document has a named owner
   • Owner responsible for quarterly review
   • Ownership transfers documented during team changes
   • Documentation included in service ownership model
2. Define documentation standards
   • Templates for each document type
   • Style guide for consistency
   • Review process for new documentation
   • Deprecation process for obsolete docs

Phase 6: Remediation Plan

1. Prioritize remediation actions
   • Critical: Create missing runbooks and incident procedures
   • High: Update stale architecture and API documentation
   • Medium: Fill onboarding and how-to guide gaps
   • Low: Improve quality of adequate-but-basic documents
2. Assign owners and deadlines
3. Establish ongoing documentation health metrics

Remediation Plan

Priority	Action	Documents	Owner	Deadline	Status
Critical	Create missing runbooks	list
High	Update stale architecture docs	list
Medium	Fill onboarding gaps	list
Low	Quality improvements	list

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

• Documentation Inventory: Complete catalog with metadata
• Freshness Report: Classification of all documents by staleness
• Gap Analysis: Missing documentation prioritized by impact
• Quality Scores: Per-document and per-category quality ratings
• Remediation Plan: Prioritized actions with owners and deadlines

Action Items

• Complete documentation inventory across all platforms
• Assess freshness and identify stale/obsolete documents
• Identify and prioritize documentation gaps
• Score document quality on key dimensions
• Assign owners to all documentation
• Create remediation plan with deadlines
• Establish quarterly documentation health review