diataxis

What this skill does

# Diataxis Skill

> **Version:** 0.1.0
> **Framework:** Diataxis Four-Quadrant Documentation (diataxis.fr)
> **Constitutional Compliance:** Jerry Constitution v1.0
> **Knowledge Reference:** `docs/knowledge/diataxis-framework.md`

## Document Sections

| Section | Purpose |
|---------|---------|
| [Purpose](#purpose) | What the skill does and key capabilities |
| [When to Use This Skill](#when-to-use-this-skill) | Activation conditions and exclusions |
| [Available Agents](#available-agents) | Agent roster with roles, tiers, and output locations |
| [P-003 Compliance](#p-003-compliance) | Single-level nesting hierarchy and architectural rationale |
| [Invoking an Agent](#invoking-an-agent) | Three invocation patterns with examples |
| [Templates](#templates) | Per-quadrant template references |
| [Integration Points](#integration-points) | Cross-skill connections |
| [Constitutional Compliance](#constitutional-compliance) | Principle mapping |
| [Quick Reference](#quick-reference) | Common workflows table |
| [References](#references) | All referenced file paths |

This SKILL.md serves multiple audiences:

## Document Audience (Triple-Lens)

| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (ELI5)** | New users, stakeholders | [Purpose](#purpose), [When to Use](#when-to-use-this-skill), [Quick Reference](#quick-reference) |
| **L1 (Engineer)** | Developers invoking agents | [Invoking an Agent](#invoking-an-agent), [Available Agents](#available-agents), [Templates](#templates) |
| **L2 (Architect)** | Workflow designers | [P-003 Compliance](#p-003-compliance), [Integration Points](#integration-points), [Constitutional Compliance](#constitutional-compliance) |

---

## Purpose

The Diataxis skill provides **four-quadrant documentation methodology** using the Diataxis framework (diataxis.fr). Instead of writing documentation as a single undifferentiated blob, this skill separates content into four types based on two axes: practical/theoretical and acquisition/application.

### Key Capabilities

- **Quadrant-Specific Writing** -- Four specialized writer agents, each encoding the quality criteria, anti-patterns, and voice for their quadrant
- **Documentation Classification** -- T1 classifier analyzes requests against the two Diataxis axes and returns structured quadrant assignment
- **Documentation Auditing** -- T2 auditor detects quadrant mixing, coverage gaps, and quality issues in existing documentation
- **Template-Driven Output** -- Per-quadrant templates enforce structural consistency
- **Self-Review Integration** -- Writer agents apply Diataxis-specific quality checks during H-15 self-review

### The Four Quadrants

|  | **Acquisition** (learning) | **Application** (working) |
|--|:--:|:--:|
| **Practical** (doing) | Tutorials | How-to Guides |
| **Theoretical** (understanding) | Explanation | Reference |

---

## When to Use This Skill

Activate when:

- Writing new documentation for any project or skill
- Converting existing documentation to follow Diataxis quadrant structure
- Classifying whether a documentation request should be a tutorial, guide, reference, or explanation
- Auditing existing docs for quadrant mixing (the #1 documentation anti-pattern)
- Producing per-quadrant templates for consistent documentation structure

**Do NOT use when:**

- Writing code, tests, or non-documentation artifacts (use `/eng-team`)
- Performing adversarial quality review of non-documentation deliverables (use `/adversary`)
- Writing requirements specifications (use `/nasa-se`)
- The user explicitly requests free-form writing without Diataxis structure -- respect user preference per P-020

### Misclassification Recovery

If a writer agent produces the wrong document type:
1. If you know the correct type: invoke the correct writer agent directly
2. If unsure: invoke `diataxis-classifier` with a `hint_quadrant` parameter to confirm. The classifier returns a confidence level (1.00/0.85/0.70); for confidence below 0.85, use the `hint_quadrant` parameter to guide classification before proceeding.

---

## Available Agents

| Agent | Role | Cognitive Mode | Model | Tier | Output Location |
|-------|------|---------------|-------|------|----------------|
| `diataxis-tutorial` | Tutorial Writer (learning-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/tutorials/` |
| `diataxis-howto` | How-to Guide Writer (goal-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/how-to/` |
| `diataxis-reference` | Reference Writer (information-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/reference/` |
| `diataxis-explanation` | Explanation Writer (understanding-oriented) | divergent | opus | T2 | `projects/${JERRY_PROJECT}/docs/explanation/` |
| `diataxis-classifier` | Documentation Classifier | convergent | haiku | T1 | Inline result (no file output) |
| `diataxis-auditor` | Documentation Auditor | systematic | sonnet | T1 | Inline result; orchestrator persists to `projects/${JERRY_PROJECT}/audits/` |

---

## P-003 Compliance

All six agents are **workers** (invoked via Task by the caller). None include `Task` in their tools. The caller (user or orchestrator) is responsible for:

1. Invoking `diataxis-classifier` to determine the correct quadrant (optional when quadrant is unambiguous from the request)
2. Invoking the appropriate writer agent based on classification
3. Invoking `diataxis-auditor` for quality review

This design maintains P-003 single-level nesting: orchestrator -> worker only.

### Architectural Rationale

Four specialized writer agents (rather than one adaptive writer) is justified by cognitive mode differentiation: tutorial writing requires **systematic** step-by-step completeness, how-to writing requires **systematic** goal-oriented focus, reference writing requires **systematic** exhaustive coverage, and explanation writing requires **divergent** conceptual exploration. These are distinct reasoning patterns that produce measurably different output when encoded in agent identity rather than deferred to prompt-level switching. The classifier separates routing from writing; the auditor separates evaluation from production.

---

## Invoking an Agent

### Option 1: Natural Language Request

```
Write a tutorial for setting up Jerry's problem-solving skill.
```

The trigger map routes "write tutorial" to `/diataxis`, and the main context invokes `diataxis-tutorial`.

### Option 2: Explicit Agent Request

```
Use /diataxis with diataxis-classifier to classify this documentation request:
"How do I configure MCP servers in Jerry?"

Then use the appropriate writer agent based on the classification.
```

### Option 3: Task Tool Invocation (Programmatic)

Agent definitions in `skills/diataxis/agents/` follow the standard Jerry dual-file architecture (H-34). The orchestrator invokes them via the Task tool using the `jerry:diataxis-{agent}` subagent_type convention, which maps to the agent definition file at `skills/diataxis/agents/diataxis-{agent}.md`:

```
Task tool invocation:
  subagent_type: "jerry:diataxis-tutorial"
  prompt: "Write a tutorial for setting up your first Jerry project.
           Topic: Setting up your first Jerry project
           Prerequisites: Jerry installed, Claude Code configured
           Output: projects/PROJ-013-diataxis/samples/tutorial-first-project.md"
```

The same pattern applies to all six agents: `jerry:diataxis-classifier`, `jerry:diataxis-tutorial`, `jerry:diataxis-howto`, `jerry:diataxis-reference`, `jerry:diataxis-explanation`, `jerry:diataxis-auditor`. (Note: verify `jerry:` namespace support against your Claude Code version before programmatic deployment.)

---

## Templates

Per-quadrant templates are located at `skills/diataxis/templates/`:

| Template | Quadrant | Key Structural Elements |
|----------|----------|------------------------|
| `skills/diataxis/templates/tutorial-template.md` | Tutorial | Numbered step