Documentation Review & Alignment Skill

## Feature Request: Documentation Review & Alignment Skill Hi Matt — first off, I just want to say that `/grill-with-docs` is awesome. It’s been incredibly useful for interrogating documentation and improving quality through iterative questioning. I’ve been using your skills as part of a larger AI-assisted development workflow, and I’ve run into a recurring problem that I think could be a great addition to the ecosystem. --- ## Problem Over multiple iterations of building with Copilot/agents: - Documentation gradually drifts from the codebase - Agent instruction files (`copilot-instructions`, etc.) become stale or overly verbose - Architectural intent (ADRs, structure decisions) becomes inconsistently represented - Terminology and taxonomy diverge across docs While `/grill-with-docs` is excellent for deep questioning, there isn’t currently a **structured, system-level documentation review skill** that: - Cross-references docs against the codebase - Validates against architectural rules (e.g., ADRs) - Produces actionable, patch-style fixes --- ## Proposed Solution A new skill focused on **Documentation Review & Alignment**, something like: **/review-docs** ### Core capabilities: 1. **Repository-wide documentation audit** - Identify inconsistencies between documentation and code - Detect misplaced content (e.g., implementation details in conceptual docs) - Highlight duplication, ambiguity, and drift 2. **Architecture-aware validation** - Enforce patterns defined in ADRs or repo conventions - Validate documentation structure (e.g., folder taxonomy, entry points) 3. **Structured findings output** - Prioritized issues (Critical / High / Medium / Low) - Clear problem descriptions with evidence - Explicit “why it matters” context 4. **Actionable remediation** - Patch-style suggested edits (diff format) - Deterministic, agent-friendly output that can be applied in a second pass --- ## Extension: Two-Phase Workflow One thing that worked especially well in my setup is splitting into: - `/review-docs` → produces findings + proposed edits - `/fix-docs` → consumes that output and applies changes This enables: - Human review + approval loop - Safe automation of fixes afterward - Repeatable hygiene workflows --- ## Additional Opportunity: Copilot Instructions Optimization A related pain point is that `copilot-instructions` files tend to: - Grow too large over time - Accumulate redundant or low-value rules - Become harder for the model to follow effectively It would be extremely valuable if this skill also: - Identified inefficiencies in instruction files - Proposed a **shorter, higher-impact rewrite** --- ## Why this fits well with your skills You already have: - `/grill-with-docs` → deep interrogation - Other skills that guide structured thinking This would complement them by adding: ✅ **System-level consistency checking** ✅ **Architecture enforcement** ✅ **Automated remediation readiness** --- ## Example Impact In my case, running a structured review like this: - Reduced documentation ambiguity significantly - Improved onboarding clarity - Tightened alignment between agents and code behavior - Made follow-on automation (auto-fixing docs) viable --- ## Happy to Share I’ve been experimenting with prompts that implement this pattern (review → structured findings → remediation), and I’d be happy to share examples or collaborate if helpful. --- Thanks again for all the work you’ve put into these skills — they’re genuinely changing how I (and I’m sure many others) build.