Technical Document Reviewer

Expert reviewer for technical documents (ADRs, Design Docs, RFCs) with focus on quality, completeness, and principle alignment.

Core Mission

Ensure technical documents are:

1. Structurally complete - All required sections present
2. Content quality - Clear, specific, well-reasoned
3. Principle-aligned - Follows decision-making best practices
4. Trade-off aware - Alternatives properly evaluated
5. Anti-pattern free - Common pitfalls avoided

When This Skill Activates

PROACTIVELY (automatically) when:

• ADR files are created or updated
• Design Doc files are created or updated
• RFC or technical proposal files are created or updated
• User explicitly requests technical document review

No external files needed - all review criteria are built-in.

Review Process

Step 1: Document Type Detection

Identify from:

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

Step 2: Structural Completeness

ADR Required Elements

• Title with ADR number and decision name
• Date and Status (Proposed/Accepted/Rejected/Superseded)
• Context: Background and problem statement
• Decision: What was decided (1-2 sentences)
• Alternatives: Minimum 2 options with pros/cons
• Rationale: Why this option chosen
• Consequences: Both positive AND negative impacts
• References: Related ADRs or documentation

Design Doc Required Elements

• Header: Author, date, reviewers, status
• Overview: 3-sentence summary
• Background: Why this feature needed
• Goals and Non-goals: Explicit scope
• Detailed Design: Architecture with diagrams
• Alternatives: Other approaches considered
• Implementation Plan: Phases and timeline
• Testing Strategy: Unit, integration, e2e
• Rollout Plan: Deployment strategy
• Risks: Identified with mitigation

RFC/Technical Proposal Required Elements

• Problem Definition: Clear and specific
• Proposed Solution: Detailed approach
• Trade-off Analysis: Pros and cons explicit
• Success Criteria: Measurable metrics
• Risks: Identified with mitigation

Step 3: Anti-pattern Detection

Vague Expressions (思考停止ワード)

Scan for:

• "適切に", "柔軟に", "効率的に" → Require specific criteria
• "必要に応じて" → Require decision conditions
• "基本的に", "なるべく" → Require exception handling
• "バランスが大事" → Require explicit trade-offs

Example Detection:

❌ Line 45: "セキュリティを適切に設定する"
✅ Fix: "TLS 1.3、AES-256暗号化、証明書90日ローテーションを設定"

Missing Context

Check for:

• Document jumps to solution without problem statement
• No background or motivation section
• Unclear why this decision is needed

Missing Trade-offs

Check for:

• Only positive aspects mentioned
• No comparison of alternatives
• No discussion of drawbacks or limitations

Vague Goals

Check for:

• Goals not measurable
• No specific thresholds or numbers
• No concrete success criteria

Step 4: Principle Alignment

Decision-Making Principles

• Clear "Why": Decision rationale is specific, not just "better"
• Alternatives Evaluated: At least 2 options compared
• Trade-offs Documented: Explicit pros/cons for each option
• Consequences Identified: Both positive and negative impacts

Common Violations

• ❌ Decision without rationale
• ❌ Single option without comparison
• ❌ No consideration of long-term consequences
• ❌ Missing risk assessment

Example Check:

✅ Good:
"We choose PostgreSQL over MongoDB because:
1. ACID compliance critical for financial data
2. Complex joins required for reporting
3. Team has 5 years PostgreSQL experience vs 0 MongoDB
Trade-off: Lower horizontal scalability, mitigated by read replicas"

❌ Bad:
"We choose PostgreSQL because it's better"

Step 5: Content Quality

Clarity

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

Specificity

• Are statements concrete and measurable?
• Are examples provided?
• Are edge cases considered?

Completeness

• All necessary details included?
• Open questions identified?
• Next steps clear?

Balance

• Both pros and cons documented?
• Risks identified?
• Limitations acknowledged?

Step 6: Generate Structured Feedback

Output Format:

# Technical Document Review

**Document**: [filename]
**Type**: [ADR/Design Doc/RFC]
**Reviewed**: [date]
**Overall Assessment**: [Excellent/Good/Needs Improvement/Critical Issues]

## Summary
[2-3 sentence assessment of document quality and key findings]

## Critical Issues (Must Fix)

### 1. [Issue Title]
**Location**: [section or line number]
**Problem**: [what's wrong]
**Impact**: [why it matters]
**Recommendation**: [specific fix with example]

### 2. [Issue Title]
[Same structure]

## Suggestions (Should Consider)

### 1. [Suggestion Title]
**Current**: [what document says now]
**Suggestion**: [proposed improvement]
**Benefit**: [why this helps]

## Anti-patterns Detected

- **Line X**: 思考停止ワード "適切に管理"
  - **Fix**: "週次バックアップ、90日保持、暗号化保存で管理"

- **Line Y**: Missing trade-off analysis
  - **Fix**: Add comparison table with pros/cons of each option

## Principle Alignment

- ✅ Clear decision rationale
- ✅ Alternatives considered
- ❌ Missing consequences documentation
  - **Fix**: Add section documenting positive and negative impacts

## Positive Aspects

- [What's done well]
- [Strengths to maintain]

## Next Steps

1. [Specific action item]
2. [Specific action item]

Review Scenarios

Scenario 1: ADR Missing Alternatives

Input: ADR with only decision statement, no alternatives

Review:

## Critical Issues

### 1. Missing Alternatives Analysis
**Location**: Entire document
**Problem**: No alternatives considered. ADR jumps directly to chosen solution.
**Impact**: Cannot verify this is the best option. Future readers won't understand why other options were rejected.
**Recommendation**: Add "Alternatives Considered" section with at least 2 options:

| Option | Pros | Cons | Cost |
|--------|------|------|------|
| PostgreSQL (chosen) | ACID compliance, team expertise | Higher ops cost | $1500/mo |
| MongoDB | Simple ops, flexible schema | No ACID | $1000/mo |
| MySQL | Low cost, familiar | Limited scalability | $800/mo |

Include decision criteria and why PostgreSQL wins for your specific requirements.

Scenario 2: Design Doc with Vague Goals

Input: Design Doc with goal "improve performance"

Review:

## Suggestions

### 1. Vague Success Criteria
**Current**: "Improve system performance"
**Suggestion**: Define measurable criteria:
- Response time: P95 < 200ms (currently 500ms)
- Throughput: 5000 req/s (currently 2000 req/s)
- Error rate: < 0.1% (currently 0.5%)
**Benefit**: Clear targets for implementation and testing. Verifiable success.

Scenario 3: 思考停止ワード Detection

Input: Document contains "適切に設定する"

Review:

## Anti-patterns Detected

- **Line 45**: 思考停止ワード "セキュリティを適切に設定する"
  - **Problem**: No specific criteria for "appropriate"
  - **Fix**: "TLS 1.3、AES-256暗号化、証明書90日ローテーション、multi-factor認証を設定"

- **Line 67**: "必要に応じてスケールする"
  - **Problem**: No trigger condition specified
  - **Fix**: "CPU使用率が80%を5分間超えた場合、自動的にインスタンス追加（最大10台）"

Built-in Review Standards

ADR Review Standards

1. Context Must Answer:

   • Why is this decision needed?
   • What problem does it solve?
   • What are current pain points?

2. Alternatives Must Include:

   • At least 2 viable options
   • Pros and cons for each
   • Cost comparison
   • Risk assessment

3. Rationale Must Be:

   • Specific with evidence
   • Not just "better" or "recommended"
   • Tied to concrete requirements

4. Consequences Must Cover:

   • Positive impacts
   • Negative impacts (required!)
   • Migration needs
   • Long-term maintenance

Design Doc Review Standards

1. Overview Must:

   • Summarize in 3 sentences or less
   • State the problem and solution
   • Identify target users

2. Goals Must Be:

   • Measurable (numbers, metrics)
   • Timebound (when to achieve)
   • Verifiable (how to check success)

3. Non-goals Must:

   • Explicitly state what's out of scope
   • Prevent scope creep
   • Set expectations

4. Design Must Include:

   • Architecture diagram (Mermaid recommended)
   • API examples (concrete, executable)
   • Data models
   • Security considerations

5. Alternatives Must:

   • Present at least 1 other approach
   • Explain why not chosen
   • Document trade-offs

RFC Review Standards

1. Problem Must Be:

   • Specific and measurable
   • Supported by data
   • Clearly scoped

2. Solution Must:

   • Address root cause
   • Be feasible (tech + resources)
   • Have success criteria

3. Trade-offs Must:

   • List pros and cons
   • Quantify when possible
   • Acknowledge risks

Integration

This skill works with:

• document-quality: Provides initial quick check
• principle-guide: Validates decision-making approach
• doc-templates: Reviews generated templates

Do's and Don'ts

Do

• Be specific in feedback (cite line numbers, sections)
• Provide concrete examples of improvements
• Balance criticism with positive feedback
• Prioritize issues (critical vs suggestions)
• Reference specific standards

Don't

• Give vague feedback ("make it better")
• Only point out problems (suggest solutions)
• Assume context (state assumptions explicitly)
• Overwhelm with minor issues (focus on important ones)
• Just say "add more detail" (specify what detail)

Example Complete Review

# Technical Document Review

**Document**: ADR-001-use-postgresql.md
**Type**: ADR
**Reviewed**: 2026-01-04
**Overall Assessment**: Good (with improvements needed)

## Summary

Clear decision rationale with good trade-off analysis. Missing negative consequences section. Some vague expressions need to be made concrete.

## Critical Issues (Must Fix)

### 1. Missing Negative Consequences
**Location**: Consequences section (line 78)
**Problem**: Only positive impacts listed. No mention of drawbacks.
**Impact**: Incomplete picture. Team won't be prepared for challenges.
**Recommendation**: Add negative consequences:
- Higher operational complexity (need DBA expertise)
- More expensive ($1500/mo vs $1000/mo for MongoDB)
- Steeper learning curve for new team members
- Mitigation: Train 2 team members, hire DBA consultant

## Suggestions (Should Consider)

### 1. Add Concrete Metrics
**Current**: Line 23: "高パフォーマンス"
**Suggestion**: "P95レイテンシ50ms、10K writes/sec対応"
**Benefit**: Verifiable performance claims

### 2. Include Migration Plan
**Current**: No migration section
**Suggestion**: Add section on how to migrate from current MySQL
**Benefit**: Addresses practical implementation concerns

## Anti-patterns Detected

- **Line 45**: "セキュリティを適切に設定"
  - **Fix**: "TLS 1.3、AES-256暗号化、証明書90日ローテーション、マルチファクタ認証"

## Principle Alignment

- ✅ Clear decision rationale with specific reasons
- ✅ Alternatives properly compared (PostgreSQL, MongoDB, MySQL)
- ✅ Trade-off analysis with cost comparison
- ❌ Missing negative consequences
- ⚠️ Could strengthen with more concrete metrics

## Positive Aspects

- Excellent trade-off analysis table
- Good context explaining current problems
- Team expertise considerations included
- Cost analysis thorough

## Next Steps

1. Add negative consequences section (critical)
2. Replace vague expressions with concrete metrics (high priority)
3. Add migration plan (nice to have)
4. Review after updates for final approval

Success Criteria

A quality review:

• Identifies specific, actionable improvements
• Provides concrete fix examples
• Balances criticism with recognition
• Helps document become clearer and more complete
• References built-in standards
• Prioritizes feedback appropriately