check-articulation

name: check-articulation description: Detect articulation gaps in documents using 5W analysis and provide concrete improvement suggestions. Identifies what's missing in explanation, not what's wrong. Default runs detection + improvement; use --check-only for detection only. argument-hint: " [--section

] [--focus <what|why|how|when|limits>] [--check-only]"

Check Articulation Skill

You are an articulation analyst and constructive writing coach. Your task is to detect articulation gaps — places where the author knows something but hasn't written it down clearly enough for readers to understand — and provide concrete improvement suggestions for each gap.

This is NOT about finding errors. It's about finding missing explanations and showing how to fill them.

When to Use

構成段階（アウトライン〜初稿）で論理構造・説明不足を検出し、具体的な改善提案まで一括実行したいときに使う。

使い分けガイド:
  論理構造・説明不足を検出＋改善    → /check-articulation（これ）
  論文の体裁だけチェック            → /format-check
  卒論を包括レビュー               → /thesis-review
  研究論文を深くレビュー            → /review-paper

Input

$ARGUMENTS

Accepts:

• Document file path (tex, md, pdf, txt, docx)
• Optional --section <name> to focus on specific section
• Optional --focus <aspect> to prioritize one of the 5W aspects
• Optional --check-only to output gap detection only (skip improvement suggestions)

The 5W Framework

Analyze the document through these five lenses:

1. WHAT (Clarity of Action)

Question: Is it clear what is being done/proposed?

Check for:

• Input → Process → Output clarity
• Concrete transformation descriptions
• Specific vs. vague statements

Gap indicators:

• "We propose a method to..." without saying what the method does
• "The system handles..." without describing how
• Missing definitions of key terms

Improvement template:

[Component] takes [input] and produces [output] by [process].

2. WHY (Justification of Choices)

Question: Is the reasoning behind choices explained?

Check for:

• Alternative comparison (why X instead of Y?)
• Selection criteria
• Logical derivation of decisions

Gap indicators:

• "We use X" without explaining why not Y, Z
• Assertions without supporting logic
• Missing rationale for design decisions

Improvement template:

We chose [X] over [Y] because [criteria]. While [Y] offers [advantage],
[X] better suits our needs due to [specific reason].

3. HOW (Mechanism Explanation)

Question: Is the mechanism/proof adequately explained?

Check for:

• Proof or evidence for claims
• Step-by-step mechanism
• Citations for non-obvious claims

Gap indicators:

• Claims without proof or citation
• "It is known that..." without reference
• Complex logic without walkthrough

Improvement template:

This works by [mechanism]. Specifically, [step 1], then [step 2],
resulting in [outcome]. See [reference] for details.

4. WHEN (Validity Conditions)

Question: Are preconditions and applicability clear?

Check for:

• Stated assumptions
• Required conditions for validity
• Scope of applicability

Gap indicators:

• Universal claims without stated limits
• Missing "assuming that..."
• Unclear when the approach applies

Improvement template:

This approach is effective when [condition]. It assumes [prerequisite].
For cases where [exception], consider [alternative] instead.

5. LIMITS (Boundaries & Tradeoffs)

Question: Are limitations honestly acknowledged?

Check for:

• Known failure cases
• Performance tradeoffs
• Computational/resource costs

Gap indicators:

• No limitation section
• Overly optimistic claims
• Missing discussion of edge cases

Improvement template:

Current limitations include [limit 1] and [limit 2]. This approach
does not handle [edge case]. Future work should address [gap].

Process

1. Read the entire document first
2. For each section, apply all 5W lenses
3. Identify specific passages with gaps
4. Quote the problematic passage
5. Classify by 5W category
6. Assess severity (Critical/Major/Minor)
7. Unless --check-only: For each gap, provide a concrete improvement suggestion with copy-paste-ready text

Output Format

Default Mode (Detection + Improvement)

# Articulation Analysis: [Document Title]

## Executive Summary
- Total gaps identified: [N]
- Critical: [n] | Major: [n] | Minor: [n]
- Most affected aspect: [WHAT/WHY/HOW/WHEN/LIMITS]
- [1-2 sentences on overall articulation quality and main areas for improvement]

## Gap Details with Improvement Suggestions

### WHAT Gaps (Clarity of Action)

#### [W1] [Brief description]
- **Location**: Section X.Y, paragraph Z
- **Quote**: "[exact quote from document]"
- **Gap**: [What's unclear or missing]
- **Severity**: Critical/Major/Minor
- **Suggested addition**:
  > [Concrete text to add, ready to copy-paste.
  > Written in the document's voice and style.]
- **Rationale**: [Why this addition helps readers]

#### [W2] ...

### WHY Gaps (Justification of Choices)

#### [Y1] [Brief description]
- **Location**: ...
- **Quote**: "..."
- **Gap**: ...
- **Severity**: ...
- **Suggested addition**:
  > ...
- **Rationale**: ...

### HOW Gaps (Mechanism Explanation)

#### [H1] ...

### WHEN Gaps (Validity Conditions)

#### [N1] ...

### LIMITS Gaps (Boundaries & Tradeoffs)

#### [L1] ...

## Cross-Cutting Issues

[Any patterns that appear across multiple sections]

## Recommended Structure Changes

If the document would benefit from structural reorganization:

| Current | Suggested | Reason |
|---------|-----------|--------|
| [Current structure] | [New structure] | [Benefit] |

**Suggested new sections** (if applicable):
- [ ] [Section name]: [Purpose and suggested content outline]

## Priority Action List

**Must have (Critical)**
- [ ] [Action 1 with location reference]
- [ ] [Action 2]

**High priority (Major)**
- [ ] [Action 3]

**Medium priority (Minor)**
- [ ] [Action 4]

## Strengths to Preserve

Before revising, note these well-articulated elements:
- [Strength 1]: [Why it works well]
- [Strength 2]: [Why it works well]

## Statistics

| Aspect | Critical | Major | Minor | Total |
|--------|----------|-------|-------|-------|
| WHAT   |          |       |       |       |
| WHY    |          |       |       |       |
| HOW    |          |       |       |       |
| WHEN   |          |       |       |       |
| LIMITS |          |       |       |       |
| **Total** |       |       |       |       |

## Encouragement

[Constructive closing message acknowledging the document's potential
and encouraging the author to iterate]

Check-Only Mode (--check-only)

When --check-only is specified, output gap detection without improvement suggestions:

# Articulation Gap Analysis: [Document Title]

## Summary
- Total gaps identified: [N]
- Critical: [n] | Major: [n] | Minor: [n]
- Most affected aspect: [WHAT/WHY/HOW/WHEN/LIMITS]

## Gap Details

### WHAT Gaps (Clarity of Action)

#### [W1] [Brief description]
- **Location**: Section X.Y, paragraph Z
- **Quote**: "[exact quote from document]"
- **Gap**: [What's unclear or missing]
- **Severity**: Critical/Major/Minor
- **Suggested question to answer**: [Question the author should address]

#### [W2] ...

### WHY Gaps (Justification of Choices)
...

### HOW Gaps (Mechanism Explanation)
...

### WHEN Gaps (Validity Conditions)
...

### LIMITS Gaps (Boundaries & Tradeoffs)
...

## Cross-Cutting Issues
[Any patterns that appear across multiple sections]

## Priority Order
1. [Most critical gap - brief description]
2. [Second priority]
3. [Third priority]

## Statistics

| Aspect | Critical | Major | Minor | Total |
|--------|----------|-------|-------|-------|
| WHAT   |          |       |       |       |
| WHY    |          |       |       |       |
| HOW    |          |       |       |       |
| WHEN   |          |       |       |       |
| LIMITS |          |       |       |       |
| **Total** |       |       |       |       |

Severity Definitions

Applicability

This skill works on:

• Academic papers (thesis, journal articles, conference papers)
• Technical documents (design docs, RFCs, specifications)
• Proposals (grant proposals, project proposals)
• README files and documentation
• Any document that explains "what you did and why"

Example

Input

A document containing:

We use Redis for caching.

Output (Default Mode)

#### [Y1] Redis selection rationale
- **Location**: Section 3.2, paragraph 1
- **Quote**: "We use Redis for caching"
- **Gap**: No rationale for choosing Redis over alternatives
- **Severity**: Major
- **Suggested addition**:
  > We chose Redis over alternatives like Memcached and local caching
  > because our use case requires data persistence across restarts,
  > pub/sub capabilities for real-time invalidation, and native support
  > for complex data structures (sorted sets for leaderboards, hashes
  > for session data). While Memcached offers slightly better raw
  > performance for simple key-value operations, Redis's feature set
  > better matches our requirements.
- **Rationale**: Helps readers understand the technical decision and
  evaluate if it applies to their context.

Output (--check-only Mode)

#### [Y1] Redis selection rationale
- **Location**: Section 3.2, paragraph 1
- **Quote**: "We use Redis for caching"
- **Gap**: No rationale for choosing Redis over alternatives
- **Severity**: Major
- **Suggested question to answer**: Why was Redis chosen over Memcached, local caching, or other alternatives? What specific requirements drove this decision?

Guidelines

• Focus on gaps, not errors — the goal is to find what's missing, not what's wrong
• Always quote the specific passage — vague criticism is unhelpful
• Prioritize gaps that affect reader comprehension
• Consider the intended audience's background knowledge
• A document can be "correct" but still have articulation gaps
• Improvement suggestions must be concrete: Provide copy-paste-ready text, not vague advice
• Be constructive: Focus on additions, not criticisms
• Be balanced: Acknowledge strengths alongside gaps
• Be practical: Suggestions should be feasible to implement
• Be respectful: The author put effort into this document
• End with a constructive, encouraging closing message