# ROLE

You are a senior documentation engineer. Your mission: take the existing
documentation in this repository, validate it against the actual code, fix
everything that's wrong, fill every gap, and transform the result into
world-class documentation following the Diátaxis framework.

THE CODE IS THE SOURCE OF TRUTH. Documentation must match reality, not the
other way around.

# INPUT

The docs to transform:
#file:docs
#file:README.md
The codebase:
#file:pynenc
The monitoring tool for pynenc, pynmon (pynenc monitoring):
#file:pynmon
The test for pynenc and pynmon
#file:pynenc_tests

---

# PHASE 1: DISCOVERY — Map everything

## 1A: Index the documentation

Read every file in DOCS_DIR recursively. For each doc extract:

| Doc File | Topic | Diátaxis Type¹ | Modules Covered | Symbols Referenced | Last Updated (git blame) |
| -------- | ----- | -------------- | --------------- | ------------------ | ------------------------ |

¹ Classify as: Tutorial / How-To / Reference / Explanation / Mixed / Unclear

## 1B: Index the code

Scan CODE_DIR and MONITORING_DIR. Extract all PUBLIC interfaces:

- Classes and public methods (with signatures)
- Functions (with signatures)
- API endpoints / routes (method, path, handler)
- CLI commands / entry points
- Configuration keys / environment variables
- Data models / schemas

| Symbol | Kind | File:Line | Has Docstring | Documented in Docs? |
| ------ | ---- | --------- | ------------- | ------------------- |

## 1C: Index the tests

Scan TESTS_DIR. For each test file extract:

| Test File | Tests Module | Key Scenarios | Useful as Doc Example? |
| --------- | ------------ | ------------- | ---------------------- |

Focus on: setup patterns (fixtures, factories) → real usage examples;
assertions → expected behavior; integration tests → end-to-end workflows.

---

# PHASE 2: AUDIT — What's wrong and what's missing

Cross-reference the three indexes.

## 2A: Broken docs (code has changed, docs haven't)

- Symbols in docs that NO LONGER EXIST in code → BROKEN
- Symbols whose SIGNATURE CHANGED since the doc was written → OUTDATED
- Behavior described in docs that CONTRADICTS test assertions → WRONG
- Docs whose last update is >6 months older than the code they describe → SUSPECT

## 2B: Undocumented code

- Public symbols with no matching doc → MISSING
- Entire modules with zero coverage → BLIND SPOT
- MONITORING_DIR specifically: list every metric, alert, health check,
  dashboard, and integration point. Flag ALL undocumented ones.

## 2C: Structural problems (Diátaxis violations)

- Pages that MIX types (tutorial with API reference, how-to with theory) → MIXED
- Features with Reference but no How-To → INCOMPLETE
- Features with no Tutorial for first-time users → NO ONRAMP
- Design decisions with no Explanation → NO RATIONALE

Output a single prioritized action list:

| Priority | Action | Type        | Target               | Problem                               |
| -------- | ------ | ----------- | -------------------- | ------------------------------------- |
| P0       | Fix    | Stale       | auth.md              | References deleted `validate_token()` |
| P1       | Create | Reference   | monitoring/alerts.py | Zero docs exist                       |
| P1       | Split  | Mixed       | setup.md             | Mixes tutorial + reference            |
| P2       | Create | How-To      | cache/               | Reference exists, no usage guide      |
| P3       | Create | Explanation | architecture         | No design rationale documented        |

---

# PHASE 3: TRANSFORM — Fix, split, rewrite, create

Work through the action list in priority order.

## 3A: Fix stale docs

- Read the current code and tests for the feature
- Update to match current reality
- Replace broken examples with working ones derived from tests

## 3B: Split mixed pages

Separate into distinct pages, one per Diátaxis type. A page that mixes
a tutorial with API reference becomes two pages that link to each other.

## 3C: Rewrite every page to quality standard

### Diátaxis rules per type

**TUTORIAL** — Learning-oriented

- Start with what the reader will ACHIEVE, not what the tool IS
- Every step is actionable and produces a visible result
- No theory dumps — link to Explanation pages instead
- End with "what you learned" and "next steps"
- Quality test: a beginner follows it with zero prior knowledge and succeeds

**HOW-TO** — Goal-oriented

- Title is a verb phrase: "How to migrate from v2 to v3"
- Assume competence. Don't re-teach basics
- Problem → Prerequisites → Steps → Done
- Quality test: it solves exactly ONE problem, completely

**REFERENCE** — Information-oriented

- Structure mirrors the code (every public API, config option, CLI flag)
- Consistent format: name, type, default, description, example
- No opinions, no tutorials, no "why" — just facts
- Quality test: any fact findable in <30 seconds

**EXPLANATION** — Understanding-oriented

- Title as a question or concept: "Why we chose event sourcing"
- Discuss trade-offs, alternatives considered, history
- Stands alone conceptually
- Quality test: reader understands WHY, not just HOW

### Writing standards (apply to ALL types)

**Voice:**

- Active voice: "Run the command" not "The command should be run"
- Second person: "you" not "the user"
- Present tense: "Returns a list" not "Will return a list"
- Kill filler words: remove "simply", "just", "obviously", "easily", "please note"

**Structure:**

- First sentence answers "what does this page help me do?"
- Headings are scannable — skimming them alone tells the story
- Short paragraphs (≤4 lines)
- Bullet lists for 3+ related items
- Tables for structured comparisons
- Admonitions (tip/warning/note) used sparingly for genuinely critical info

**Code examples:**

- Every block must be RUNNABLE as-is — no pseudocode, no `...` ellipsis
- Derive from tests: use test setup + execution, strip assertions and mocks
- Show minimal example first, then advanced variation
- Include expected output
- Specify language for syntax highlighting
- If a command has prerequisites, state them before the block

**Navigation:**

- Every page links to its logical next step
- Tutorials → link to relevant Reference at the end
- How-Tos → "See also" linking related How-Tos
- Reference → link to Explanation for rationale
- Update the docs index/TOC with any new pages

## 3D: Create new docs where gaps exist

### For monitoring (use this template specifically):

Monitoring: {{Feature Name}}
What It Monitors
Metrics collected, health checks performed, alert conditions.

Configuration
Key Type Default Description
(from env vars, config files, constants in code)
Endpoints / Interfaces
(from routes, CLI commands, scheduled tasks)

Alerts
Alert Condition Severity Action Required
(from code)
Integration
How this connects to external systems (databases, queues, dashboards).

Runbook
What to do when an alert fires.
(Derived from error handling code and test edge cases)

### For everything else, use the Diátaxis templates:

**Reference page:**
{{Module Name}}
Reference for {{module_path}}

Overview
One paragraph: what this does and when you'd use it.

API
function_name(param1: type, param2: type) -> return_type
Description.

Parameters:

Name Type Default Description
Returns: ...

Example:

# from tests/test\_{{module}}.py

<minimal runnable example>

**How-To page:**
How to {{verb phrase}}
Prerequisites
...
Steps

1. {{First step}}

<code from test setup or integration test>
2. {{Next step}}
...

Troubleshooting
(from test assertions and edge cases)

See Also
Reference: {{module}}

---

# PHASE 4: VALIDATE

Run every page through these checklists.

## Accuracy (code is truth)

- [ ] Every symbol referenced in docs exists in current codebase
- [ ] Every function signature matches the actual code
- [ ] Every code example is extracted from or verified against tests
- [ ] Every config key / env var has a match in the code
- [ ] Monitoring docs cover ALL alerts, metrics, health checks in MONITORING_DIR
- [ ] No doc describes behavior that contradicts a passing test

## Completeness

- [ ] Every public class/function in CODE_DIR appears in at least one doc
- [ ] Every module in MONITORING_DIR has dedicated documentation
- [ ] Every feature has Reference + at least one other Diátaxis type
- [ ] A Getting Started tutorial exists and works end-to-end
- [ ] Top 10 user tasks each have a How-To guide

## Quality

- [ ] No page mixes Diátaxis types
- [ ] First sentence of every page tells the reader what it's for
- [ ] All code examples run without modification
- [ ] No jargon used without definition or link
- [ ] Headings are scannable — skimming tells the story
- [ ] No wall-of-text paragraphs (all ≤4 lines)
- [ ] Cross-links and next-steps exist on every page
- [ ] Docs TOC / index updated with all new pages

## Audience

- [ ] A beginner completes every Tutorial without external help
- [ ] An experienced user finds any Reference fact in <30 seconds
- [ ] A goal-oriented user solves their problem using only a How-To
- [ ] A curious user understands design rationale from Explanation pages

---

# PHASE 5: SCORE & DECIDE

| Dimension                  | Score /5 | Criteria for 5                              | Failing Items |
| -------------------------- | -------- | ------------------------------------------- | ------------- |
| Accuracy (docs match code) | /5       | Zero broken references, all examples run    |               |
| Completeness (coverage)    | /5       | Every public symbol documented              |               |
| Monitoring coverage        | /5       | Every alert/metric/healthcheck documented   |               |
| Structure (Diátaxis)       | /5       | All 4 types present, cleanly separated      |               |
| Clarity & writing          | /5       | No ambiguity, no filler, scannable          |               |
| Examples (from tests)      | /5       | All runnable, derived from real tests       |               |
| Navigation                 | /5       | Any fact findable in <30s, logical links    |               |
| Beginner experience        | /5       | Tutorials work end-to-end, zero assumptions |               |

### Decision rules:

- **ALL ≥ 4 → DONE.** Output the final deliverables.
- **Any = 3 → ONE MORE PASS** targeting only that dimension.
- **Any ≤ 2 → RETURN TO PHASE 2** for that dimension.
- **Average < 3.5 → FULL RESTART** from Phase 1 with lessons learned.

When iterating, touch ONLY the failing dimensions. Do not regress passing ones.

---

# FINAL OUTPUT

When done, deliver:

1. **Change manifest** — every file created / modified / deleted, with one-line summary
2. **Coverage report** — before vs after (% of public symbols documented)
3. **Monitoring inventory** — complete list of what's now documented
4. **Scorecard** — final Phase 5 scores
5. **Remaining gaps** — anything you could NOT document and why
   (no tests exist, code is ambiguous, external system not accessible)
   The flow in one picture:

DISCOVER AUDIT TRANSFORM VALIDATE DECIDE
───────── ─────── ────────── ───────── ──────
Index docs → Broken? → Fix stale docs → Accuracy → All ≥4?
Index code → Missing? → Split mixed → Complete → ├─ YES → SHIP
Index tests → Mixed types? → Rewrite to std → Quality → └─ NO → loop
Monitoring → Create new docs → Audience back to
gaps? → (w/ test examples) failing
phase
