SKILL: Review Markdown

Last Updated: February 5, 2026

Table of Contents

• •SKILL: Review Markdown
  • •Table of Contents
  • •1. Overview
    • •1.1 Persona Usage
    • •1.2 Optimization Tiers
  • •2. Optimization Techniques
  • •3. Execution Workflow
  • •4. SNIPPET Implementation Audit
  • •5. Self-Assessment Protocol
  • •6. Report Template

1. Overview

Optimizes Markdown documentation for conciseness and clarity while preserving essential content. Goals (priority order): Completeness → Clarity → Token Optimization. Uses format-markdown skill for validation.

Use when: Documentation exceeds reasonable length, redundancy detected, content duplicated from referenced files.

Do NOT use when: Document already optimized, or content cannot be reduced without losing meaning.

1.1 Persona Usage

Default Persona: Technical Writer (see RULE_Persona.md Section 2.3)

Workflow: Technical Writer lens first → document-specific persona → synthesize recommendations.

1.2 Optimization Tiers

🚨 CRITICAL: Determine tier FIRST before applying techniques.

2. Optimization Techniques

Essential Content (Must Preserve): Critical rules (🚨❌ severity), self-verification checklists, cross-references, unique information.

3. Execution Workflow

Step 1: Analyze Document

1. •Read entire document, record metrics (lines, sections, TOC)
2. •Identify document type and determine optimization tier per Section 1.2
3. •Run format-markdown skill for baseline compliance

Step 2: Plan Optimization

1. •Present analysis with identified redundancies
2. •Specify tier and target reduction range
3. •Get user approval before changes

Step 3: Apply Changes

1. •Apply tier-appropriate optimizations from Section 2
2. •Update Last Updated date if content changes
3. •Preserve all checklists (add if missing)

Step 4: Validate Results

1. •Run format-markdown skill final validation
2. •Calculate reduction metrics
3. •Verify reduction within tier target range
4. •Present results to user

Output (File): Edited target file (template: none) Output (Console): Reduction metrics (template: Section 6)

4. SNIPPET Implementation Audit

Trigger: When reviewing SNIPPET files in .ai-context/

Process:

1. •Identify corresponding IDEA file (e.g., SNIPPET_OrderProcessing.md → IDEA_OrderProcessing.md)
2. •Analyze codebase for implemented features:
   • •Check source files for matching components/services
   • •Review git commits for implementation evidence
3. •For each SNIPPET section:
   • •If fully implemented: Mark for removal
   • •If partially implemented: Keep unimplemented portions
4. •If ALL sections implemented: Recommend deleting entire file (see RULE_Document.md Section 3.4)

Verification:

• • Codebase files checked against SNIPPET code
• • Git history reviewed for implementation commits
• • Corresponding IDEA sections cross-referenced
• • Removal recommendations documented with evidence

5. Self-Assessment Protocol

🚨 CRITICAL: Before presenting results, verify:

• • Optimization tier correctly identified per Section 1.2
• • Tier-appropriate techniques applied throughout
• • Reduction percentage within tier target range
• • All critical rules (🚨/❌ severity) preserved
• • Self-verification checklists maintained or added
• • Cross-references accurate and files exist
• • Key workflows and processes intact
• • format-markdown skill validation passed
• • Last Updated date current (if content changed)
• • TOC updated to reflect new structure
• • Before and after line counts recorded

6. Report Template

Key Changes:

• •{change_description} (e.g., Consolidated sections, Converted to tables)