Documentation Review Guidance

Audit, improve, and maintain documentation quality across the repository. Search for doc files — don't rely on hardcoded paths.

Architecture Maintenance

For ARCHITECTURE-FLOW.md updates, load .github/skills/understanding-architecture/SKILL.md first — it has validation commands and source-of-truth mappings.

SKILL.md Quality Gates

Naming rules (agentskills.io spec):

• ✅ writing-csharp-code (lowercase, hyphens, max 64 chars)

• ❌ WritingCSharpCode | writing--csharp | -writing-code

Required frontmatter: name (must match directory name), description (must explain WHAT and WHEN, max 1024 chars)

Body must include: goal statement, practical code examples, common mistakes, related skill cross-references.

.agent.md Quality Gates

Required frontmatter: name , description , argument-hint , tools , model

Verify: handoffs reference valid agent name values from other agent files.

copilot-instructions.md

Loads on every request — keep it lean. Must have: architecture quick reference, dev commands, agents table, skills table.

Audit Checklists

ARCHITECTURE-FLOW.md

• Mermaid diagrams render without syntax errors

• State machines match appState.ts type definitions

• SSE events match Program.cs Write*Event methods

• Actions match AppAction type union

README.md

• Quick start works for new users

• Commands table is accurate

• Links to sub-READMEs resolve

Skills & Agents

• Valid YAML frontmatter on all files

• SDK versions in examples match *.csproj / package.json

• Cross-references between skills are valid

Cross-Document Consistency

• Architecture tables match across all docs

• Port numbers consistent (5173, 8080)

• SDK versions match actual dependencies

Review Output Format

For each document reviewed:

Document: path/to/file.md — ✅ Good | ⚠️ Needs Improvement | ❌ Broken

Issues: numbered list with suggested fixes

Cross-Reference Issues: broken links, version mismatches

Style Rules

• Code blocks: always include language identifier (typescript not )

• Links: relative paths for internal, absolute for external

• Tables: consistent column widths

Constraints

• ❌ Don't change code (only docs)

• ❌ Don't invent features not in codebase