Document Quality Checker

Automatically review technical documents based on best practices and quality checklists.

Quick Start

This skill automatically activates when you create or update:

• ADR (Architecture Decision Record)
• Design Document
• Meeting notes or prep sheets
• Technical proposals or RFCs

No external files needed - all checks are built-in.

Supported Document Types

ADR (Architecture Decision Record)

Detection: Filename contains "ADR" or has ADR structure Required sections: Context, Decision, Alternatives, Rationale, Consequences

Design Doc

Detection: Filename contains "design-doc" or has Design Doc structure Required sections: Overview, Background, Goals, Design, Alternatives, Plan

Meeting Notes/Preparation

Detection: Contains meeting agenda or decision materials Required sections: Purpose, Participants, Decision materials, Options

Technical Proposals/RFCs

Detection: Contains proposal or RFC structure Focus: Problem definition, Trade-off analysis, Concrete examples

Review Process

Step 1: Detect Document Type

Identify from:

• Filename patterns (ADR-, design-doc-, meeting-, RFC-)
• Document structure (headings)
• Content markers

Step 2: Structural Check

Verify all required sections exist based on type.

ADR Required Sections

• Title with decision name
• Date and status
• Context (background and problem)
• Decision statement
• Alternatives considered (minimum 2)
• Decision rationale
• Consequences (positive AND negative)
• Related decisions/references

Design Doc Required Sections

• Header (author, date, reviewers, status)
• Overview (concise summary)
• Background and motivation
• Goals and non-goals (explicit)
• Detailed design with diagrams
• Alternatives considered
• Implementation plan
• Testing strategy
• Rollout/deployment plan

Meeting Prep Required Sections

• Meeting purpose (decision/consultation/sharing)
• Participants list
• Background and problem
• Options with pros/cons
• Recommendation with rationale

Step 3: Anti-pattern Detection

See [ANTIPATTERNS.md](ANTIPATTERNS.md) for full catalog.

Common Anti-patterns

1. 思考停止ワード (Vague Expressions)

❌ Detected phrases:

• "適切に", "柔軟に", "効率的に" (appropriately, flexibly, efficiently)
• "必要に応じて" (as needed)
• "基本的に", "なるべく" (basically, preferably)
• "バランスが大事" (balance is important)

✅ Fix: Replace with specific criteria

❌ "データベースを適切に選択"
✅ "トラフィック1000req/s以下ならPostgreSQL、超える場合Cassandra"

❌ "パフォーマンスを改善"
✅ "レスポンスタイム500ms→200ms以下に改善"

❌ "必要に応じてスケール"
✅ "CPU使用率80%を5分間超えたら自動スケール"

2. Missing Context

❌ Problem: Document jumps to solution without explaining why

✅ Fix: Add background section explaining:

• Current situation
• Problem to solve
• Why this decision is needed

3. Missing Trade-offs

❌ Problem: Only positive aspects mentioned

✅ Fix: Add comparison table:

4. No Concrete Examples

❌ Problem: Abstract descriptions only

✅ Fix: Add concrete examples:

• Code snippets
• API examples
• Sample data
• Use cases

5. Vague Goals

❌ "Improve system performance" ✅ "Reduce P95 latency from 500ms to <200ms"

❌ "Enhance security" ✅ "Implement TLS 1.3, AES-256 encryption, 90-day cert rotation"

Step 4: Content Quality Check

Clarity

• Can a new team member understand this?
• Is jargon explained?
• Are assumptions stated?

Specificity

• Are statements measurable?
• Are thresholds/numbers provided?
• Are edge cases considered?

Completeness

• Are all necessary details included?
• Are open questions identified?
• Are next steps clear?

Balance

• Are both pros and cons documented?
• Are risks identified?
• Are limitations acknowledged?

Step 5: Generate Feedback

Output format:

## Document Quality Review

**Document Type**: [ADR/Design Doc/Meeting Prep/etc.]
**Overall Assessment**: [Excellent/Good/Needs Improvement/Critical Issues]

### Summary
[2-3 sentence assessment]

### Critical Issues (Must Fix)

1. **Missing Section: Alternatives**
   - Location: Entire document
   - Problem: No alternatives considered
   - Impact: Cannot verify this is the best option
   - Fix: Add section with at least 2 alternatives and trade-off analysis

2. **Vague Expression: Line 45**
   - Detected: "セキュリティを適切に設定"
   - Problem: No specific criteria
   - Fix: "TLS 1.3、AES-256暗号化、証明書90日ローテーション"

### Suggestions (Should Consider)

1. **Add Concrete Metrics**
   - Current: "Improve performance"
   - Suggestion: "Reduce P95 latency to <200ms (currently 500ms)"

2. **Include Diagrams**
   - Add architecture diagram (Mermaid recommended)
   - Add sequence diagram for complex flows

### Positive Aspects

- Clear decision rationale
- Well-structured trade-off analysis
- Concrete examples provided

### Checklist Results

ADR Completeness: 7/8 sections ✅
- ✅ Context
- ✅ Decision
- ✅ Alternatives
- ✅ Rationale
- ❌ Negative consequences (missing)
- ✅ Related decisions

Built-in Checklists

Document Creation Checklist

Before publishing any technical document:

• Purpose is clear: Can state objective in one sentence
• Audience identified: Know who will read this and their level
• Structure is logical: Follows established template
• Context provided: Background explains why this matters
• Concrete examples: At least 2-3 specific examples
• No vague expressions: Checked for 思考停止ワード
• Trade-offs documented: Pros and cons explicitly listed
• Metrics are measurable: Numbers, thresholds, or criteria provided
• Next steps clear: Action items or follow-ups identified

Vague Expression Checklist

Check for these patterns and replace with specifics:

ADR Specific Checklist

• Decision is stated clearly: One sentence summary
• Minimum 2 alternatives: With pros/cons for each
• Trade-off table: Quantitative comparison
• Rationale is specific: Not just "better" or "recommended"
• Negative consequences: Explicitly documented
• Migration plan: If replacing existing system
• Review date: When to revisit this decision

Design Doc Specific Checklist

• 3-sentence overview: Captures essence of design
• Goals AND non-goals: Explicit scope boundaries
• Success metrics: Measurable (latency, throughput, etc.)
• Architecture diagram: Visual representation
• API examples: Concrete request/response
• Alternative designs: At least 1 other approach considered
• Security reviewed: Authentication, authorization, encryption
• Testing strategy: Unit, integration, e2e plans
• Rollout plan: Phased deployment with rollback

Anti-pattern Detection Examples

Example 1: Vague Adverb

Input: "パフォーマンスを適切に改善する"

Detection: "適切に" (vague adverb)

Feedback:

❌ Detected: 思考停止ワード "適切に"
   Location: Line 23
   Problem: No specific criteria for "appropriate"

✅ Fix: "レスポンスタイムを200ms以下に改善（現在500ms）"

Example 2: Missing Trade-offs

Input: ADR with only chosen option, no alternatives

Detection: No "Alternatives" section

Feedback:

❌ Critical Issue: Missing Alternatives Analysis
   Location: Entire document
   Problem: No alternatives considered. Cannot verify best option.
   Impact: Future readers won't understand why other options rejected.

✅ Fix: Add "Alternatives Considered" section:
   | Option | Pros | Cons | Cost |
   |--------|------|------|------|
   | PostgreSQL (chosen) | ACID, team expertise | Higher ops cost | $1500/mo |
   | MongoDB | Simple ops, flexible schema | No ACID | $1000/mo |

Example 3: Vague Goals

Input: "システムの性能を向上させる"

Detection: No metrics

Feedback:

❌ Vague Goal Detected
   Current: "システムの性能を向上させる"
   Problem: Not measurable

✅ Fix: "以下の性能目標を達成:
   - P95レイテンシ: 500ms → 200ms以下
   - スループット: 2000 req/s → 5000 req/s
   - エラー率: 0.5% → 0.1%以下"

Integration

Works alongside:

• doc-templates: Reviews generated templates
• tech-doc-reviewer: Provides initial quick check
• principle-guide: Validates decision-making process

Activation

Automatically activates when:

• Creating/editing files matching patterns (ADR-, design-doc-, etc.)
• Document structure matches known types
• User requests "review document quality"

Limitations

• Pattern-based detection (not semantic analysis)
• Japanese 思考停止ワード focus
• Requires documents to follow common structures

Getting Help

For detailed anti-pattern catalog: [ANTIPATTERNS.md](ANTIPATTERNS.md)

For templates: Use doc-templates skill

For detailed review: tech-doc-reviewer agent provides deeper analysis