@femtomc/mu-agent 26.3.3 → 26.3.5

package/README.md

@@ -45,7 +45,7 @@ They are organized as category meta-skills plus subskills:
   - `setup-discord`
   - `setup-telegram`
   - `setup-neovim`
-- `writing`
+- `technical-writing`
 
 Starter skills are version-synced by CLI bootstrap. Initial bootstrap seeds missing
 skills; bundled-version changes refresh installed starter skill files.
@@ -77,7 +77,7 @@ Current stack:
 
 - `brandingExtension` — mu compact header/footer branding + default theme
 - `eventLogExtension` — event tail + watch widget
-- `uiExtension` — programmable `UiDoc` surface (`/mu ui ...`, `mu_ui`)
+- `uiExtension` — programmable `UiDoc` surface (`/mu ui ...`, `mu_ui`) with session-resume persistence via `custom` entries (`mu-ui-state/v1`)
 
 Default operator UI theme is `mu-gruvbox-dark`.
 

package/dist/extensions/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/extensions/ui.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAq/CpF,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,QAkO3C;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/extensions/ui.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA0qDpF,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,QA4P3C;AAED,eAAe,WAAW,CAAC"}

package/dist/extensions/ui.js

@@ -1,4 +1,4 @@
-import { normalizeUiDocs, parseUiDoc, resolveUiStatusProfileName, uiStatusProfileWarnings, } from "@femtomc/mu-core";
+import { normalizeUiDocs, parseUiDoc, resolveUiStatusProfileName, stableSerializeJson, uiStatusProfileWarnings, } from "@femtomc/mu-core";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { registerMuSubcommand } from "./mu-command-dispatcher.js";
 const UI_DISPLAY_DOCS_MAX = 16;
@@ -6,6 +6,8 @@ const UI_PICKER_COMPONENTS_MAX = 8;
 const UI_PICKER_LIST_ITEMS_MAX = 4;
 const UI_PICKER_KEYVALUE_ROWS_MAX = 4;
 const UI_SESSION_KEY_FALLBACK = "__mu_ui_active_session__";
+const UI_STATE_CUSTOM_TYPE = "mu-ui-state/v1";
+const UI_STATE_SCHEMA_VERSION = 1;
 const UI_PROMPT_PREVIEW_MAX = 160;
 const UI_INTERACT_SHORTCUT_PRIMARY = "ctrl+shift+u";
 const UI_INTERACT_SHORTCUT_FALLBACK = "alt+u";
@@ -46,6 +48,7 @@ function createState() {
         interactionDepth: 0,
         lastStatusText: null,
         lastWidgetSignature: null,
+        lastPersistSignature: null,
     };
 }
 function pruneStaleStates(nowMs) {
@@ -389,6 +392,164 @@ function parseDocListInput(value) {
     }
     return { ok: true, docs: normalizeUiDocs(docs, { maxDocs: UI_DISPLAY_DOCS_MAX }) };
 }
+function normalizeStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+function parsePersistedPendingPrompt(value) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    const kind = value.kind === "action" || value.kind === "review" ? value.kind : null;
+    if (!kind) {
+        return null;
+    }
+    const uiIdRaw = typeof value.ui_id === "string" ? value.ui_id.trim() : "";
+    if (!uiIdRaw) {
+        return null;
+    }
+    const actionIdRaw = typeof value.action_id === "string" ? value.action_id.trim() : "";
+    if (kind === "review") {
+        return { kind, ui_id: uiIdRaw };
+    }
+    if (actionIdRaw) {
+        return { kind, ui_id: uiIdRaw, action_id: actionIdRaw };
+    }
+    return { kind, ui_id: uiIdRaw };
+}
+function parsePersistedUiState(value) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    if (value.v !== UI_STATE_SCHEMA_VERSION) {
+        return null;
+    }
+    const parsedDocs = parseDocListInput(value.docs);
+    if (!parsedDocs.ok) {
+        return null;
+    }
+    const pendingPrompts = [];
+    const pendingRaw = Array.isArray(value.pending_prompts) ? value.pending_prompts : [];
+    for (const pending of pendingRaw) {
+        const parsed = parsePersistedPendingPrompt(pending);
+        if (parsed) {
+            pendingPrompts.push(parsed);
+        }
+    }
+    return {
+        v: 1,
+        docs: parsedDocs.docs,
+        pending_prompts: pendingPrompts,
+        prompted_revision_keys: normalizeStringArray(value.prompted_revision_keys),
+        awaiting_ui_ids: normalizeStringArray(value.awaiting_ui_ids),
+    };
+}
+function serializeUiState(state) {
+    retainPromptedRevisionKeysForActiveDocs(state);
+    retainAwaitingUiIdsForActiveDocs(state);
+    retainPendingPromptsForActiveDocs(state);
+    const docs = activeDocs(state, UI_DISPLAY_DOCS_MAX);
+    return {
+        v: 1,
+        docs,
+        pending_prompts: state.pendingPrompts.map((pending) => ({
+            kind: pending.kind,
+            ui_id: pending.uiId,
+            ...(pending.actionId ? { action_id: pending.actionId } : {}),
+        })),
+        prompted_revision_keys: [...state.promptedRevisionKeys].sort((left, right) => left.localeCompare(right)),
+        awaiting_ui_ids: [...state.awaitingUiIds].sort((left, right) => left.localeCompare(right)),
+    };
+}
+function uiStatePersistSignature(value) {
+    return stableSerializeJson(value);
+}
+function persistUiStateSnapshot(pi, state) {
+    const snapshot = serializeUiState(state);
+    const signature = uiStatePersistSignature(snapshot);
+    if (state.lastPersistSignature === signature) {
+        return;
+    }
+    pi.appendEntry(UI_STATE_CUSTOM_TYPE, snapshot);
+    state.lastPersistSignature = signature;
+}
+function applyPersistedUiState(state, persisted) {
+    state.docsById.clear();
+    state.pendingPrompts = [];
+    state.promptedRevisionKeys.clear();
+    state.awaitingUiIds.clear();
+    state.interactionDepth = 0;
+    state.lastStatusText = null;
+    state.lastWidgetSignature = null;
+    for (const doc of persisted.docs) {
+        state.docsById.set(doc.ui_id, doc);
+    }
+    for (const revisionKey of persisted.prompted_revision_keys) {
+        state.promptedRevisionKeys.add(revisionKey);
+    }
+    for (const uiId of persisted.awaiting_ui_ids) {
+        state.awaitingUiIds.add(uiId);
+    }
+    for (const pending of persisted.pending_prompts) {
+        enqueuePendingPrompt(state, {
+            kind: pending.kind,
+            uiId: pending.ui_id,
+            actionId: pending.action_id,
+        });
+    }
+    retainPromptedRevisionKeysForActiveDocs(state);
+    retainAwaitingUiIdsForActiveDocs(state);
+    retainPendingPromptsForActiveDocs(state);
+    state.lastPersistSignature = uiStatePersistSignature(serializeUiState(state));
+}
+function latestPersistedUiStateFromBranch(entries) {
+    let latest = null;
+    for (const entry of entries) {
+        if (!isPlainObject(entry)) {
+            continue;
+        }
+        if (entry.type !== "custom" || entry.customType !== UI_STATE_CUSTOM_TYPE) {
+            continue;
+        }
+        const parsed = parsePersistedUiState(entry.data);
+        if (!parsed) {
+            continue;
+        }
+        latest = parsed;
+    }
+    return latest;
+}
+function restoreStateFromSessionBranch(ctx, key) {
+    const manager = ctx.sessionManager;
+    const branch = typeof manager.getBranch === "function" ? manager.getBranch() : [];
+    const restored = createState();
+    const persisted = latestPersistedUiStateFromBranch(branch);
+    if (persisted) {
+        applyPersistedUiState(restored, persisted);
+    }
+    const nowMs = Date.now();
+    pruneStaleStates(nowMs);
+    STATE_BY_SESSION.set(key, {
+        state: restored,
+        lastAccessMs: nowMs,
+    });
+    return restored;
+}
 function statusProfileWarningsExtraForDoc(doc) {
     const warnings = uiStatusProfileWarnings(doc);
     if (warnings.length === 0) {
@@ -1355,6 +1516,7 @@ export function uiExtension(pi) {
         removePendingPromptsForUiId(state, selectedDoc.ui_id);
         retainAwaitingUiIdsForActiveDocs(state);
         retainPendingPromptsForActiveDocs(state);
+        persistUiStateSnapshot(pi, state);
         ctx.ui.notify(`Submitted prompt from ${selectedDoc.ui_id}/${selectedAction.id}.`, "info");
     });
     registerMuSubcommand(pi, {
@@ -1432,15 +1594,35 @@ export function uiExtension(pi) {
             if (ctx.hasUI && result.ok && result.changedUiIds && result.changedUiIds.length > 0) {
                 armAutoPromptForUiDocs(state, result.changedUiIds);
             }
+            const shouldPersistMutation = result.ok &&
+                (result.action === "set" ||
+                    result.action === "update" ||
+                    result.action === "replace" ||
+                    result.action === "remove" ||
+                    result.action === "clear");
+            if (shouldPersistMutation) {
+                persistUiStateSnapshot(pi, state);
+            }
             refreshUi(ctx);
             return buildToolResult({ state, ...result });
         },
     });
-    pi.on("session_start", (_event, ctx) => {
+    const restoreAndRefresh = (ctx) => {
+        const key = sessionKey(ctx);
+        restoreStateFromSessionBranch(ctx, key);
         refreshUi(ctx);
+    };
+    pi.on("session_start", (_event, ctx) => {
+        restoreAndRefresh(ctx);
     });
     pi.on("session_switch", (_event, ctx) => {
-        refreshUi(ctx);
+        restoreAndRefresh(ctx);
+    });
+    pi.on("session_fork", (_event, ctx) => {
+        restoreAndRefresh(ctx);
+    });
+    pi.on("session_tree", (_event, ctx) => {
+        restoreAndRefresh(ctx);
     });
     pi.on("agent_end", async (_event, ctx) => {
         if (!ctx.hasUI) {
@@ -1453,6 +1635,7 @@ export function uiExtension(pi) {
         if (!pending) {
             return;
         }
+        persistUiStateSnapshot(pi, state);
         if (pending.kind === "action") {
             ctx.ui.notify(`Agent requested input via ${pending.uiId}. Submit now or press ${UI_INTERACT_SHORTCUT_HINT} later.`, "info");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.3.3",
+  "version": "26.3.5",
   "description": "Shared operator runtime for mu assistant sessions and serve extensions.",
   "keywords": [
     "mu",
@@ -24,7 +24,7 @@
     "themes/**"
   ],
   "dependencies": {
-    "@femtomc/mu-core": "26.3.3",
+    "@femtomc/mu-core": "26.3.5",
     "@mariozechner/pi-agent-core": "^0.54.2",
     "@mariozechner/pi-ai": "^0.54.2",
     "@mariozechner/pi-coding-agent": "^0.54.2",

package/prompts/skills/core/mu/SKILL.md

@@ -263,4 +263,4 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
   - **`setup-discord`**
   - **`setup-telegram`**
   - **`setup-neovim`**
-- Technical writing/docs polish: **`writing`**
+- Technical writing/docs polish: **`technical-writing`**

package/prompts/skills/technical-writing/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: technical-writing
+description: "Produces clear, argument-driven technical prose. Use when drafting or reviewing systems papers, design docs, READMEs, PR descriptions, error messages, API references, or other technical communication."
+---
+
+# technical writing
+
+Use this skill when asked to write, edit, or review technical prose. This includes research/systems papers, design docs, RFCs, READMEs, PR descriptions, commit messages, error messages, API references, and postmortems.
+
+This skill emphasizes argument quality (why the work matters, why choices are defensible, what evidence supports claims), not just sentence polish.
+
+## Source foundations
+
+This guidance synthesizes:
+
+- Dan Cosley, *Writing more useful systems papers, maybe* (reader value + "why" over "what")
+- Kayvon Fatahalian, *What Makes a (Graphics) Systems Paper Beautiful* (goals/constraints, organizing insight, design decisions, evaluation causality)
+- Daniel Ritchie, *Three-phase Paper Writing* (phase-based drafting and feedback loops)
+- Roy Levin and David Redell, *How (and How Not) to Write a Good Systems Paper* (originality/reality/lessons/choices/context/focus/presentation rubric)
+
+## Contents
+
+- [Core contract](#core-contract)
+- [Core argument spine](#core-argument-spine)
+- [Writing workflows](#writing-workflows)
+- [Section checklists (papers and deep technical docs)](#section-checklists-papers-and-deep-technical-docs)
+- [Common crash landings](#common-crash-landings)
+- [Editing and review workflow](#editing-and-review-workflow)
+- [Evaluation scenarios](#evaluation-scenarios)
+- [Quality bar](#quality-bar)
+
+## Core contract
+
+1. **Reader value over author chronology**
+   - Do not write "what I did" narratives.
+   - Write for what the reader should understand, decide, or do after reading.
+
+2. **Lead with why**
+   - State why the problem matters before deep implementation detail.
+   - Make stakes explicit: who benefits, what improves, what becomes possible.
+
+3. **Define problem shape explicitly**
+   - State goals, non-goals, constraints, and assumptions.
+   - If these are unclear, the design cannot be evaluated fairly.
+
+4. **Name the central insight**
+   - State the organizing principle in plain language.
+   - A system artifact is not the contribution by itself; the transferable insight is.
+
+5. **Explain choices, not just outcomes**
+   - Highlight key design decisions and why they were chosen.
+   - Discuss meaningful alternatives and tradeoffs.
+   - Separate core decisions from incidental implementation details.
+
+6. **Attach evidence to claims**
+   - For each major claim, provide concrete evidence.
+   - Evaluate whether the proposed decisions caused the observed results.
+   - Prefer claim-by-claim validation over a single undifferentiated benchmark dump.
+
+7. **State lessons and limits**
+   - Tell readers what generalizes and what does not.
+   - Be explicit about assumptions and boundary conditions.
+
+8. **Avoid revisionist history**
+   - Do not present a magically linear path if work was iterative.
+   - Briefly documenting failed paths and surprises increases credibility and usefulness.
+
+9. **Write for scanability and precision**
+   - Strong headings, short paragraphs, concrete nouns, consistent terminology.
+   - Define terms before use; minimize forward references.
+
+10. **Polish matters**
+    - Clear grammar, correct spelling, and coherent figure captions are part of technical quality, not cosmetics.
+
+## Core argument spine
+
+Use this skeleton for most substantial technical writing:
+
+1. **Problem and stakes**: What problem exists, and why should this reader care now?
+2. **Gap**: Why current approaches are insufficient under real constraints.
+3. **Insight**: The key idea / organizing observation.
+4. **Approach**: What was built/proposed and the major decisions.
+5. **Evidence**: What data, experiments, deployments, or analysis support each claim.
+6. **Implications**: What new capability or practical outcome this enables.
+7. **Limits**: Assumptions, non-goals, failure modes, and open questions.
+
+If a section cannot map to this spine, it is often off-topic, under-motivated, or prematurely detailed.
+
+## Writing workflows
+
+### A) Systems/research paper workflow (phase-based)
+
+#### Phase 0: contribution test (before full drafting)
+
+- Can the central idea be stated in one short paragraph?
+- Is the problem specific and meaningful?
+- Is the contribution significant enough for the venue?
+- Is related work understood deeply enough to establish novelty?
+- Is the work implemented or otherwise justified at the level needed for credibility?
+
+If these answers are weak, improve the work/story before expanding prose.
+
+#### Phase I: section-level outline
+
+Use a stable scaffold:
+
+1. Introduction
+2. Related Work / Context
+3. Approach Overview
+4. Method / Design sections
+5. Results / Evaluation
+6. Discussion / Limitations / Future Work
+
+At outline time:
+- List explicit contributions in the introduction.
+- Name evaluation subsections early (for example: ablations, latency, usability, robustness).
+- Capture known limitations as a running list.
+
+#### Phase II: sentence-level skeleton
+
+- Write one line per intended sentence.
+- Focus on information content, not elegance.
+- Ensure each section’s opening paragraph states what is in the section and why it matters.
+- For every important design decision, add explicit justification and mention alternatives.
+- Draft figure/table placeholders early so missing evidence is visible.
+
+#### Phase III: polish and technical precision
+
+- Convert skeleton text into clear prose.
+- Tighten wording, remove repetition, standardize terminology.
+- Upgrade captions so figures stand alone.
+- Add citations and math formatting.
+- Finalize abstract once argument and evidence are stable.
+
+Note: drafting a short contribution summary early is useful; final abstract text should still be revised late.
+
+#### Phase IV+: feedback loops
+
+- Early feedback: argument, framing, contribution clarity.
+- Late feedback: explanation gaps, ambiguity, wording, factual correctness.
+- Iterate until reviewers can identify contributions and evidence without guessing.
+
+### B) Design docs and RFCs
+
+Recommended structure:
+
+1. Problem context and impact
+2. Goals, non-goals, and constraints
+3. Proposed design and key decisions
+4. Alternatives considered (and why rejected)
+5. Validation plan and success metrics
+6. Rollout/migration plan
+7. Risks, failure modes, and mitigations
+8. Open questions
+
+Treat design docs as decision records, not implementation diaries.
+
+### C) PR descriptions and commit messages
+
+Use this order:
+1. **What changed**
+2. **Why this change was needed**
+3. **How to verify** (exact commands/tests)
+4. **Risk / rollout / breaking changes**
+
+Keep summaries imperative and concrete.
+
+### D) Error messages and user-facing diagnostics
+
+Include:
+1. What happened
+2. Why (if known)
+3. What the user can do next
+4. Context IDs/paths/log pointers
+
+Bad: "Operation failed"
+
+Better:
+```
+Error: Could not load config from /etc/mu/config.json.
+Cause: JSON parse error at line 48 (trailing comma).
+Fix: Remove the trailing comma and re-run `mu control reload`.
+Details: parser_error_code=EJSON_TRAILING_COMMA
+```
+
+## Section checklists (papers and deep technical docs)
+
+### Introduction
+
+- Does it clearly establish problem importance?
+- Are constraints and context realistic?
+- Are explicit contributions listed?
+- Can a busy reader understand the paper’s value from this section alone?
+
+### Related work / context
+
+- Is comparison explicit (similarities and differences), not name-dropping?
+- Are prior works treated respectfully and accurately?
+- Does this section sharpen the novelty claim?
+
+### Design / approach
+
+- Are key decisions distinguished from implementation detail?
+- Are alternatives and tradeoffs discussed?
+- Are assumptions explicit?
+- Is there a clear organizing principle?
+
+### Evaluation
+
+- Is each major claim tested directly?
+- Do results explain *why* outcomes occurred, not only *that* they occurred?
+- Are baselines/comparators fair and clearly described?
+- Are limitations and threats to validity disclosed?
+
+### Discussion / conclusion
+
+- Are lessons explicit and transferable?
+- Are boundaries and non-generalizable aspects named?
+- Are future directions grounded in observed limits (not generic filler)?
+
+## Common crash landings
+
+- Leading with implementation detail before problem significance.
+- "Summer vacation" narrative: chronology without transferable lessons.
+- Listing features instead of defending decisions.
+- Claiming novelty without explicit comparison to prior work.
+- Hiding assumptions or omitting non-goals.
+- Evaluating only aggregate outcomes while ignoring causal design claims.
+- Presenting a cleaned-up fictional process (revisionist history).
+- Related-work sections that only attack others or only list citations.
+- Forward-reference overload and undefined terms.
+- Sloppy grammar/formatting that signals weak rigor.
+
+## Editing and review workflow
+
+When reviewing existing prose:
+
+1. **Structural pass**
+   - Is the document organized around reader questions?
+   - Are sections ordered by decision value (why -> what -> evidence -> implications)?
+
+2. **Argument pass**
+   - Highlight major claims.
+   - Verify each claim has evidence and scope.
+   - Flag assertions without backing.
+
+3. **Design-decision pass**
+   - Confirm key decisions are explicit.
+   - Check whether alternatives and tradeoffs are discussed.
+
+4. **Evidence pass**
+   - Validate that evaluation supports claimed contributions.
+   - Check reproducibility details (versions, commands, datasets, parameters).
+
+5. **Language pass**
+   - Convert vague phrases to measurable statements.
+   - Remove redundancy and filler.
+   - Ensure consistent terminology and active voice where useful.
+
+6. **Final polish**
+   - Verify figures/tables/captions stand on their own.
+   - Fix grammar/spelling/format consistency.
+   - Read key sections aloud for clarity.
+
+## Evaluation scenarios
+
+1. **Systems paper draft review**
+   - Prompt: user asks why reviews say "interesting system, weak paper".
+   - Expected: identify missing problem framing, unclear central insight, absent design-rationale discussion, or evaluation-claim mismatch.
+
+2. **Design doc quality upgrade**
+   - Prompt: user provides an implementation-heavy RFC.
+   - Expected: restructure around goals/constraints, key decisions, alternatives, and validation plan.
+
+3. **PR description improvement**
+   - Prompt: user shares a vague PR summary.
+   - Expected: rewrite into what/why/how-to-verify/risk with concrete commands.
+
+4. **Diagnostic message rewrite**
+   - Prompt: user shares generic errors.
+   - Expected: produce actionable what/why/fix/details messages with identifiers and next steps.
+
+## Quality bar
+
+- Reader can state the problem, insight, and contribution after a quick skim.
+- Major claims are backed by explicit evidence.
+- Key decisions and tradeoffs are visible.
+- Limits and assumptions are acknowledged honestly.
+- Prose is clear, concrete, and respectful of reader time.

package/prompts/skills/writing/SKILL.md

@@ -1,180 +0,0 @@
----
-name: writing
-description: "Crafts clear, precise technical documentation. Use when writing or reviewing docs, PR descriptions, error messages, READMEs, API references, or any technical prose."
----
-
-# writing
-
-Use this skill when asked to write, edit, or review technical prose. This includes documentation, READMEs, PR descriptions, error messages, comments, API references, and commit messages.
-
-## Contents
-
-- [Core contract](#core-contract)
-- [Writing workflows](#writing-workflows)
-- [Common patterns by document type](#common-patterns-by-document-type)
-- [Editing and review workflow](#editing-and-review-workflow)
-- [Evaluation scenarios](#evaluation-scenarios)
-- [Quality bar](#quality-bar)
-
-## Core contract
-
-1. **Audience first**
-   - Identify the reader's baseline knowledge before writing.
-   - Write for the busiest reader who needs this information.
-   - Honor their time: front-load the essential information.
-
-2. **Clarity over style**
-   - One idea per sentence. Complex concepts deserve their own space.
-   - Active voice: "The system returns an error" not "An error is returned by the system."
-   - Precise terminology: use the same word for the same concept throughout.
-   - Concrete over abstract: "200ms latency" beats "fast performance."
-
-3. **Structure for scanability**
-   - Headings should communicate the document structure without reading prose.
-   - Lists for parallel items (bullets for unordered, numbers for sequences).
-   - Code blocks and tables over prose descriptions.
-   - Inverted pyramid: conclusion, supporting details, background.
-
-4. **Actionability**
-   - Imperative for procedures: "Run the command" not "The command should be run."
-   - Explicit consequences: state what happens if the user does X.
-   - Anticipate failure modes in troubleshooting sections.
-
-5. **Accessibility**
-   - Plain language: avoid Latin abbreviations, buzzwords, metaphor-heavy descriptions.
-   - Sentence length: average 15-20 words. Vary rhythm but never confuse length with sophistication.
-   - Context for jargon: define domain-specific terms on first use or link to definitions.
-
-6. **Verify by reading aloud**
-   - Awkward phrasing surfaces when spoken.
-   - Test instructions by following them exactly as written.
-   - Delete mercilessly: if a sentence doesn't inform or direct, cut it.
-
-## Writing workflows
-
-### A) Documentation from scratch
-
-1. **Identify the audience and goal**
-   - Who will read this? What do they know? What must they do after reading?
-
-2. **Outline the structure**
-   - Opening paragraph: what this document covers and why it matters.
-   - Body: group related concepts, sequence procedures in order of execution.
-   - Closing: next steps, related resources, or troubleshooting.
-
-3. **Draft with constraints**
-   - Maximum 25 words per sentence on average.
-   - Active voice for all instructions.
-   - Code examples for any behavior described.
-
-4. **Review against the contract**
-   - Scan test: can a reader grasp structure from headings alone?
-   - Action test: can a reader execute procedures without asking questions?
-   - Deletion pass: remove sentences that don't inform or direct.
-
-### B) PR/commit description
-
-1. **What changed** (imperative, present tense)
-2. **Why it changed** (context, motivation)
-3. **How to verify** (testing steps, expected outcomes)
-4. **Breaking changes** (if any, with explicit adoption guidance)
-
-Keep under 80 characters per line in the summary. Body wraps at 72 characters.
-
-### C) Error messages
-
-1. **State what happened** (not what didn't)
-2. **Explain why** (the root cause, if known)
-3. **Provide the fix** (concrete next step, not generic advice)
-4. **Include identifiers** (error codes, relevant IDs, log locations)
-
-Example:
-```
-Error: Connection refused to database 'prod-db' on port 5432.
-Cause: The database service is not running or firewall blocks port 5432.
-Fix: Start the service with 'sudo systemctl start postgresql' or verify firewall rules.
-Log: See /var/log/postgresql/postgresql-14-main.log for details.
-```
-
-## Common patterns by document type
-
-### README.md
-
-Structure:
-1. One-line description of what this is
-2. Installation/usage (minimal working example)
-3. Key features (bullet list)
-4. Configuration/options
-5. Contributing/troubleshooting links
-
-### API documentation
-
-Per endpoint:
-- Purpose (one sentence)
-- HTTP method and path
-- Parameters (name, type, required, description)
-- Request/response examples
-- Error codes and meanings
-
-### Inline code comments
-
-- **Why**, not what: explain intent, not obvious behavior.
-- Non-obvious side effects or assumptions.
-- TODO/FIXME with issue references, not vague notes.
-- Public APIs: docstrings with parameters, returns, raises.
-
-### Configuration docs
-
-- Default values explicitly stated.
-- Units for all numeric values (ms, bytes, percent).
-- Validation constraints (min/max, allowed values).
-- Impact of changing the value (what breaks, what improves).
-
-## Editing and review workflow
-
-When reviewing existing prose:
-
-1. **Structural audit**
-   - Does the outline serve the reader's goal?
-   - Are headings descriptive? Is sequencing logical?
-
-2. **Sentence-level edits**
-   - Convert passive to active voice.
-   - Replace vague quantifiers ("some", "many") with specifics.
-   - Break long sentences (\> 25 words) into two.
-
-3. **Accuracy check**
-   - Verify all code examples execute as written.
-   - Confirm version numbers, paths, and URLs are current.
-   - Check that error messages match actual output.
-
-4. **Final polish**
-   - Read aloud for awkward rhythm.
-   - Consistent formatting (punctuation in lists, code fences with languages).
-   - Spelling and grammar (but prioritize clarity over grammatical perfection).
-
-## Evaluation scenarios
-
-1. **Drafting documentation for a new feature**
-   - Prompt: user asks for docs for a feature they've implemented.
-   - Expected: skill identifies audience, structures around user goals not implementation details, includes working examples, and ends with verification steps.
-
-2. **Reviewing a PR description**
-   - Prompt: user shares a draft PR description for feedback.
-   - Expected: skill checks for imperative summary line, clear what/why/how structure, and explicit breaking change notice if applicable.
-
-3. **Improving error messages**
-   - Prompt: user shares error handling code or current error text.
-   - Expected: skill transforms vague messages into specific what/why/fix format with actionable next steps and relevant identifiers.
-
-4. **Editing README for clarity**
-   - Prompt: user asks for help with a project's README.
-   - Expected: skill restructures for inverted pyramid, adds minimal working example, replaces feature paragraphs with scannable lists, and ensures installation steps are complete and ordered.
-
-## Quality bar
-
-- Every sentence earns its place: informs or directs.
-- No sentence requires a second reading to understand.
-- A reader can act on instructions without asking clarifying questions.
-- Code examples execute without modification.
-- A skim reader grasps the document's purpose and structure.