@femtomc/mu-agent 26.3.4 → 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-agent",
-  "version": "26.3.4",
+  "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.4",
+    "@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.