devrites 7.1.2 → 7.2.0

package/pack/generated/dsh/skills/devrites-prose-craft/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: devrites-prose-craft
+description: Rewrite prose to remove AI tells while preserving meaning and voice. Use for artifacts, replies, commits, or PR copy; not code comments or UI craft.
+user-invocable: false
+---
+<!-- loads: {"always":["devrites-lib/reference/standards/prose-style.md"],"triggers":{"word-choice":["devrites-prose-craft/reference/banned-phrases.md"],"structure":["devrites-prose-craft/reference/structures.md"],"examples":["devrites-prose-craft/reference/examples.md"]}} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --skill devrites-prose-craft` (no workspace: `--out <path>`) bundles every file named below into one deduplicated read. Trigger names map to the conditional rules in the sections that follow.
+
+# devrites-prose-craft: prose that reads human
+
+Write for a teammate who will rely on the result. Remove model-shaped filler without sanding
+off the author's voice or weakening technical content.
+
+## When this fires
+- A text-generating phase composes an artifact: `/rite-spec` (overview, rationale),
+  `/rite-define` / `/rite-plan` (plan narrative), `/rite-temper` / `/rite-vet` (review prose),
+  `/rite-review` / `/rite-seal` (findings + verdict prose), `/rite-ship` (commit/PR body),
+  `devrites-doubt` / `/rite-handoff` (notes).
+- Any phase composes substantive **user-facing prose** beyond the shared reply
+  labels.
+
+## Two modes
+- **Rewrite (default).** When DevRites writes the artifact/reply or polishes it, fix the prose
+  in place.
+- **Detect-only.** When auditing prose you shouldn't silently change, such as a user's existing
+  `spec.md` at `/rite-adopt` or text under `/rite-review`, list the tells with quotes and leave
+  the text untouched. Mirrors `devrites-audit`'s read-only stance.
+
+Order findings by severity: **P0** credibility-killers (vague attribution, a marketing
+adjective standing in for evidence, a false/unsourced claim, cutoff disclaimers, unfilled
+placeholders, citation markup, AI-tool tracking URLs) → **P1** obvious tells (negative
+parallelism, filler openers, em-dash tics, reasoning-chain scaffolding, narrated candor)
+→ **P2** polish (rhythm, word choice, 1B clarity edits). A quick pass fixes P0 + P1 and
+stops; a full pass takes P2 too. Flags are writing-quality signals, not authorship proof.
+In detect-only, report Tier 1A (figurative filler) separately from Tier 1B (wordiness).
+
+## Process
+
+1. **Calibrate.** Choose rewrite or detect-only mode, split prose from technical sections, and
+   set the voice baseline: an explicit user sample first, then neighboring project prose, then
+   the source text itself. Fall back to flat, direct prose. Done when every section has a
+   register and one voice baseline.
+2. **Protect.** Apply the preservation contract in
+   [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md) before changing words.
+   Leave tables, YAML frontmatter, URLs, and file paths untouched unless the caller asked to
+   change them. Scan for clusters of tells; one isolated marker is not a verdict. Done when
+   every claim, constraint, identifier, example, quotation, and deliberate uncertainty is
+   accounted for. Admitted reviewer rows (`Finding:`/`Basis:`), `Outcome:`/`Verdict:`
+   lines, counts, and the candidate binding are technical register: skip them, because
+   [`agents.md`](../devrites-lib/reference/standards/agents.md#return-budget) § Return budget
+   (the root never rewrites an admitted row) wins over this skill.
+3. **Rewrite.** Remove P0/P1 tells and P2 when the caller asked for a full pass. Match the
+   baseline's vocabulary and cadence without inventing facts, opinions, or quirks. Done when the
+   same reader can make the same decisions from the rewrite as from the source.
+4. **Audit.** Compare source and result, read the prose aloud, and run the relevant references
+   below. Diff severity labels, REQ/AC/finding IDs, counts, verdict words, rankings,
+   order/causality claims, and `file:line` pointers between source and result; any
+   difference fails the pass. Done when the preservation contract passes, the technical
+   register remains exact, and no in-scope tell remains. **Failing case:** a pass turns
+   "3 Important" into "several issues" or upgrades a hedged note to "Critical".
+
+## References
+
+- Always read [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md) for the two
+  registers, preservation contract, and core checks.
+- Load [`reference/banned-phrases.md`](reference/banned-phrases.md) when word choice or tone is
+  the problem (trigger `word-choice`).
+- Load [`reference/structures.md`](reference/structures.md) when sentence shape, rhythm, or
+  formatting is the problem.
+- Load [`reference/examples.md`](reference/examples.md) when the target artifact's shape is
+  unclear.
+
+## Boundaries
+
+This skill edits language, not facts. When style and fidelity conflict, fidelity wins.
+
+## Output
+
+- **Rewrite:** replace the target prose; add no editing commentary unless the caller's contract
+  asks for it.
+- **Detect-only:** return ordered P0/P1/P2 findings with the exact phrase and a concrete fix.

package/pack/generated/dsh/skills/devrites-prose-craft/reference/banned-phrases.md

@@ -0,0 +1,132 @@
+# Phrases & words to cut
+
+Load this when scrubbing prose. The lists are calibrated for a coding agent: the **AI
+vocabulary** section marks which words are *always* slop versus which are legitimate in
+technical writing, so the skill doesn't flatten a real spec into vagueness.
+
+## Throat-clearing openers (cut — state the point)
+
+- "Here's the thing:" / "Here's what / why / how [X]"
+- "It's worth noting that" / "It's important to note that"
+- "Let me be clear" / "I'll be honest" / "To be honest"
+- "The uncomfortable truth is" / "The reality is" / "It turns out"
+- "Make no mistake" / "At its core" / "At the end of the day"
+- "When it comes to [X]" / "In today's [fast-paced / digital] world"
+
+Any "here's what/this/that" or "it's worth noting" is runway before the point. Delete it and
+start at the point.
+
+## Emphasis crutches (delete — they add no information)
+
+- "Let that sink in." / "Full stop." / "Period."
+- "This matters because" / "Here's why that matters"
+- "This is the deepest problem" / "the stakes are high" / "the consequences are real"
+- "Notably," / "Interestingly," / "Importantly," / "Surprisingly," stacked to tell the
+  reader how to feel. One "notably" in a long note is fine; three in a short paragraph
+  is emphasis stacking. Cut the cue; leave the fact.
+
+## Hedging stacks (make the claim or cut it)
+
+- "it's important to note that, generally, in most cases…"
+- "perhaps", "could potentially", "it could be argued that", "one might say"
+
+Stacked hedges read as a model covering itself. One honest qualifier is fine; a stack is slop.
+
+## Sycophancy & chatbot artifacts (remove entirely)
+
+These leak the assistant register into artifacts and replies:
+
+- "Great question!" / "You're absolutely right!" / "Certainly!" / "Of course!"
+- "I hope this helps!" / "Let me know if you need anything else" / "Feel free to reach out"
+- "Let's explore" / "Let's break this down" / "Let's dive in" / "First, let's consider"
+
+A `decisions.md` entry or a `seal.md` verdict is a document, not a chat turn. No
+pleasantries, no tour-guide openers. Start at the point.
+
+## Assistant leaks (P0 — delete on sight)
+
+These are paste fingerprints, not style. Strip the leak; keep any real fact it was
+wrapping. Presence is a publishing bug, not an authorship tribunal.
+
+- **Cutoff disclaimers.** "As of my last update", "based on my training data", "I don't
+  have access to…". Find the fact or drop the sentence.
+- **Unfilled placeholders.** `[Your Name]`, `[INSERT SOURCE]`, `2025-XX-XX`, HTML
+  comments that say `TODO` / `insert` / `fill in`. Fill or delete. Never ship the slot.
+- **Citation markup.** `citeturn`, `oaicite`, `oai_citation`, `grok_card`,
+  `[attached_file:N]`. Delete the token. If the cite mattered, replace it with a real
+  link.
+- **AI-tool tracking URLs.** Strip `utm_source=chatgpt.com` / `copilot.com` /
+  `openai` / `claude.ai` / `perplexity.ai` and `referrer=grok.com`. Keep the rest of
+  the query string (`?page=2` stays).
+
+## Business jargon → plain language
+
+| Avoid | Use instead |
+|---|---|
+| Navigate (challenges) | handle, address |
+| Unpack (the analysis) | explain, examine |
+| Lean into | accept, commit to |
+| Landscape (figurative) | situation, field, area |
+| Game-changer | significant, important |
+| Deep dive | analysis, examination |
+| Circle back / revisit later | return to |
+| Moving forward | next, from now on |
+| On the same page | aligned, agreed |
+
+## AI vocabulary — calibrated (this is the adaptation that matters)
+
+Word lists are blunt instruments. A coding agent must not "fix" a spec that legitimately says
+a system is *robust* under load or exposes a *comprehensive* API. Tiers, with a 1A/1B split:
+
+**Tier 1A — always slop, replace on sight (figurative filler, never load-bearing in a spec).**
+A cluster is a writing-quality signal, not proof of who wrote the passage.
+
+delve / delve into, tapestry, beacon, embark, testament to, realm, landscape (figurative),
+pave the way, shed light on, game-changer, unlock the potential, ever-evolving, vibrant,
+multifaceted, holistic, paradigm (as praise), groundbreaking, transformative, cutting-edge.
+
+**Tier 1B — always replace for clarity; not authorship evidence.**
+Wordiness and inflated formality. Same edit as 1A, weaker claim: these also appear in
+careful human writing. In detect-only, report 1B separately from 1A. A 1B hit must not
+push a passage toward an "AI wrote this" conclusion.
+
+| Replace | With |
+|---|---|
+| utilize | use |
+| in order to | to |
+| due to the fact that | because |
+| commence | start, begin |
+| ascertain | find out, determine |
+| endeavor | try, attempt |
+
+**Tier 2 — slop in prose, legitimate in technical context (keep the meaning, judge by use):**
+robust, comprehensive, seamless, leverage, harness, facilitate, underpin, streamline,
+foster, ecosystem, scalable.
+- In a sentence selling the work ("a robust, scalable, seamless solution") → cut; say what it
+  does and what proves it.
+- In a precise technical claim ("the retry path is robust to a dropped connection — see
+  `evidence.md`") → keep. The word carries a real, tested meaning.
+
+**Tier 3 — flag by density, not per-word:** ordinary words (`important`, `key`, `various`,
+`significant`) become slop only when they cluster. If a paragraph leans on three of them, it's
+saying nothing — name the specific thing instead.
+
+**Co-occurrence tell:** these words travel in packs. Where you find one Tier-1 word, look for
+its neighbours (delve / boasts / bolstered / crucial / pivotal cluster together). One sighting
+means scan the whole passage.
+
+**Match inflected forms.** Each entry covers the word *and* its variants — adverb (`-ly`),
+gerund (`-ing`), plural, conjugations: `delve` also catches `delving` / `delved`; `leverage`
+catches `leveraging` / `leveraged`. The exception is a variant with a distinct, legitimate
+meaning (`real` the intensifier vs `real` meaning factual) — judge it by use, same as the
+tier calibration above.
+
+## Adverbs (cut empty intensifiers; keep load-bearing ones)
+
+Cut the emphasis adverbs that add nothing: really, very, just, literally, genuinely, honestly,
+simply, actually, truly, fundamentally, inherently, inevitably, basically.
+
+Keep adverbs that change meaning or precision: "validate **server-side**", "fail **closed**",
+"runs **concurrently**", "**explicitly** typed". The rule is "cut the empty intensifier", not
+"delete every -ly word" — over-applying the no-adverb rule is its own kind of damage in
+technical writing.

package/pack/generated/dsh/skills/devrites-prose-craft/reference/examples.md

@@ -0,0 +1,136 @@
+# Before / after — DevRites artifacts & replies
+
+Real shapes DevRites emits. Each pair keeps the technical content and strips the voice. Note
+how the calibration preserves precise lists and identifiers while cutting the prose slop.
+
+## 1. `spec.md` overview
+
+**Before (slop):**
+> In today's fast-paced data landscape, this feature delivers a robust, scalable, and seamless
+> CSV export capability. It's not just about exporting data — it's about empowering users to
+> unlock the full potential of their information. This is a pivotal step forward.
+
+**After:**
+> Export the report table to CSV. Users currently copy rows by hand; this adds a one-click
+> download. Scope: the reports table only, server-side streaming so memory stays flat on large
+> exports.
+
+Cut the jargon, the negative-parallelism hook, and the importance inflation. Kept what the
+feature is, who it's for, and the scope boundary.
+
+## 2. Acceptance criteria (technical register — precision stays)
+
+**Keep this as-is — do NOT "humanize" it:**
+> - AC-001: A `GET /reports/:id/export?format=csv` returns `200` with `Content-Type: text/csv`.
+> - AC-002: Rows stream; peak memory stays under 50 MB for a 1M-row export.
+> - AC-003: An unknown `format` returns `400` with `{ "error": "unsupported format" }`.
+
+Three items, exact identifiers, exact status codes. This is the technical register working
+correctly. The skill leaves it alone.
+
+## 3. `decisions.md` entry
+
+**Before (slop):**
+> We made the strategic decision to leverage a streaming approach. This robust solution
+> seamlessly handles large datasets and represents a best-in-class architecture that will
+> empower the system to scale effortlessly.
+
+**After:**
+> Stream rows to the response instead of buffering the full file. Buffering OOM-ed on a
+> 1M-row export in testing (see `evidence.md`). Trade-off: streaming rules out a total-row
+> count in the header. Revisit if the UI needs an upfront progress bar.
+
+Named the decision, the reason (with evidence), and the trade-off. That's what an ADR is for.
+
+## 4. `review.md` / `seal.md` finding
+
+**Before (slop):**
+> Important: it's worth noting that the error handling at `export.ts:42` could potentially be
+> more robust, which fundamentally matters for production readiness. It catches every error and
+> returns `500 "something went wrong"`, even for a bad `format` param, where AC-003 expects a
+> `400` with the specific message. Catching the parse error narrowly and letting the rest
+> propagate would arguably be the way to go.
+
+**After:**
+> Important — `export.ts:42` catches every error and returns `500 "something went wrong"`. A
+> bad `format` param should be a `400` with the specific message (AC-003). Catch the parse error
+> narrowly; let the rest propagate.
+
+Kept the stated severity, `file:line`, status codes, and AC id; added none. A Before without
+them stays hedged in the After, never upgraded to a severity or ID it did not state.
+
+## 5. Chat reply
+
+**Before (slop):**
+> Great question! I've gone ahead and implemented the export feature. It's not just functional
+> — it's production-ready. Let me know if you need anything else!
+
+**After:**
+> Built slice 3 (CSV streaming). Tests pass (`npm test -- export` → 14 passing), peak memory
+> 38 MB on the 1M-row fixture. Next: `/rite-build` slice 4 (pagination).
+
+Dropped the pleasantries, the "not just X" inflation, and the closing offer. Led with what's
+done and the evidence; ended on one runnable next action, not a "Want me to continue?" stall.
+
+## 6. Commit body
+
+**Before (slop):**
+> This commit introduces a comprehensive and robust solution that seamlessly enables users to
+> leverage powerful new export capabilities.
+
+**After:**
+> Buffering the whole CSV OOM-ed on >100k rows. Stream rows to the response so memory stays
+> flat. Rules out an upfront total-count header; tracked in #123.
+
+Followed [`git-workflow.md`](../../devrites-lib/reference/standards/git-workflow.md): the *why*, wrapped, in plain language.
+
+## 7. Fidelity when evidence is incomplete
+
+**Before (slop, but informative):**
+> It is important to note that the importer retries twice after a `429`. The available evidence
+> does not clearly indicate whether a third attempt is dropped or queued. In either case, the
+> alert text is `Import delayed`.
+
+**After:**
+> The importer retries twice after a `429`. We do not have a production trace showing whether a
+> third attempt is dropped or queued. The alert text remains `Import delayed`.
+
+Cut the opener and vague phrasing. Kept the retry count, status code, evidence gap, two possible
+outcomes, and exact alert text. A smoother sentence that picked one outcome would be fabrication.
+
+## 8. `review.md` finding (narrated candor)
+
+**Before (slop):**
+> I want to be upfront: two caveats I would rather flag than let you discover later. First,
+> Windows is untested. Second, the numbers in the commit message don't reproduce on this
+> hardware. Let me think step by step about what that means for seal.
+
+**After:**
+> Two caveats: Windows is untested, and the numbers in the commit message don't reproduce on
+> this hardware. Seal stays NO-GO until those are measured or scoped out.
+
+Cut the candor frame and the reasoning-chain opener. Kept both caveats and the gate implication.
+
+## 9. Chat reply (prompt restatement)
+
+**Before (slop):**
+> That's a great question. You're asking about whether we should stream the export. Thanks for
+> the rollback plan you already wrote — that legwork is what made this possible. Breaking this
+> down: streaming avoids the OOM.
+
+**After:**
+> Stream the export. Buffering OOM-ed on the 1M-row fixture (see `evidence.md`). Your rollback
+> plan still applies.
+
+Dropped the prompt echo, the recap-flattery, and "Breaking this down". Led with the decision
+and the evidence.
+
+## The pattern across all nine
+
+1. Lead with the concrete thing (what it is, what's done, what's wrong).
+2. Replace every "robust/seamless/leverage" flourish with the specific behavior + its proof.
+3. Drop negative-parallelism hooks ("not just X, it's Y"), importance labels ("pivotal"),
+   candor frames ("I want to be upfront"), and reasoning-chain scaffolding ("let me think
+   step by step").
+4. Keep the technical register intact: exact identifiers, status codes, numbered criteria,
+   real enumerations. Precision is not slop.

package/pack/generated/dsh/skills/devrites-prose-craft/reference/structures.md

@@ -0,0 +1,196 @@
+# Structures to avoid
+
+The sentence- and paragraph-level shapes that mark machine-written prose. Each row is a
+pattern and its fix. Calibrated: the slop is the *decorative* version; the genuine structural
+version (a real enumeration, a real contrast that carries information) stays.
+
+## Negative parallelism — the "not X, it's Y" family
+
+The single most recognizable tell. It mimics insight by manufacturing a contrast.
+
+| Pattern | Fix |
+|---|---|
+| "It's not X, it's Y." / "It isn't X. It's Y." | State Y. "Y is the cause." |
+| "Not just X, but Y." / "Not only X but also Y." | State both plainly, or just Y if X is filler. |
+| "The question isn't X. It's Y." | Ask the real question once, or state the answer. |
+| "This isn't about X. It's about Y." | "This is about Y." |
+| "X isn't the problem. Y is." | "Y is the problem." |
+| "No X. No Y. Just Z." | "Z." or a normal sentence naming Z. |
+| Negation chain: "No fluff, no filler, no jargon." / "It didn't ask. It didn't wait." | Say what the thing is. One negation earns its place when the reader would assume the opposite; a drumroll of them does not. Carve-out: factual inventories ("takes no arguments, no headers, and no body") stay. |
+
+Drop the negation; lead with the thing you actually mean.
+
+## Rule of three / decorative tricolon
+
+AI defaults to three-item adjective or benefit triplets. The fix depends on whether the three
+items are *real*.
+
+- **Decorative triad** — "innovative, transformative, and groundbreaking", "fast, reliable, and
+  scalable" as a flourish → cut to the one that's true and provable, or delete.
+- **Real enumeration** — three acceptance criteria, three slices, three status codes the
+  endpoint returns → **keep all three.** This is precision, not slop. The technical register
+  needs the complete list.
+
+Test: if removing one item loses information a reader needs, it's a real list — keep it. If the
+three are interchangeable adjectives, it's a triad — cut it.
+
+## Importance inflation
+
+Announcing significance instead of showing it. Let the reader judge weight.
+
+| Pattern | Fix |
+|---|---|
+| "a pivotal moment", "a broader movement" | Describe what happened; drop the significance label. |
+| "The implications are significant." | Name the specific implication. |
+| "This is a critical step." | Show why it's required (the dependency, the gate, the risk). |
+
+## Vague attribution — cite the source or drop it
+
+The prose twin of DevRites's evidence discipline (`devrites-source-driven`, `evidence.md`). An
+unnamed authority is not a source; it inflates one person's claim into consensus.
+
+| Pattern | Fix |
+|---|---|
+| "Experts believe…", "Studies show…", "Research suggests…" | Name the study/doc/benchmark, or cut the appeal and state the claim on its own merits. |
+| "Best practice says…", "The community recommends…", "It's widely agreed…" | Link the source (an RFC, the framework docs, a measured result), or make the call yourself and own it in `decisions.md`. |
+
+If you can't name who holds the view, you don't have a source — you have a guess. State it as one.
+
+## Abstract category nouns — name the specific items
+
+"Various factors", "several considerations", "a number of issues" say nothing. Replace the
+category word with the actual items.
+
+| Pattern | Fix |
+|---|---|
+| "improvements across various metrics" | "cuts p95 latency 120ms→80ms and halves the query count" |
+| "there are several considerations" | List the considerations, or name the one that matters. |
+| "performance issues", "some edge cases" | Name the N+1 query; name the empty-input and the 10k-row cases. |
+
+Offender words to catch: factors, aspects, considerations, issues, elements, things, areas,
+metrics (unnamed). In a spec or `decisions.md`, the specific item is the whole point.
+
+## False agency — name who acts
+
+Giving inanimate things human verbs. Common in machine prose because it avoids naming the actor.
+
+| Pattern | Fix |
+|---|---|
+| "the data tells us" | "the grader reads X and returns Y" |
+| "the decision emerges" | "we chose X because…" |
+| "the complaint becomes a fix" | "the team fixed it in slice 3" |
+| "the test ensures correctness" | "the test asserts `total === 42`" |
+
+Front the actor: the script, the gate, the function, the engineer, or "you".
+
+## Dramatic fragmentation & rhetorical setups
+
+| Pattern | Fix |
+|---|---|
+| "[Noun]. That's it. That's the [thing]." | One complete sentence. |
+| "X. And Y. And Z." (staccato for drama) | Join into normal sentences; vary length. |
+| "The result? Devastating." (self-posed Q&A) | Fold into a statement. |
+| "What if [reframe]?" as a hook | Make the point directly. |
+| "Think about it:" / "Here's what I mean:" | Delete; the next sentence already does the work. |
+| Performed insight: "that's not nothing", "the punchline is", "sit with that", "that's the whole point", "Turns out…" | State the claim the phrase was gesturing at. One hit can be voice; several in one piece is a tell. |
+
+## Inflated constructions
+
+Three small tells that pad a plain sentence into something that sounds weightier than it is.
+
+| Pattern | Fix |
+|---|---|
+| **Copula-dodge** — "X serves as / functions as / stands as / boasts / features…" | Use the plain verb. "The gateway **is** the entry point", "the module **has** three handlers". |
+| **Participle tail** — "…, highlighting its importance", "…, reflecting broader trends", "…, underscoring its role as a dynamic hub" | Cut the trailing `-ing` clause; it adds fake depth, not information. |
+| **Aphorism formula** — "X is the Y of Z" ("caching is the heartbeat of the system"), "X is not a tool but a Y" | State the actual property. "The cache holds the hot rows so the DB isn't hit on every request." |
+| **Invented concept label** — coining a pseudo-term as if it's established: "the N+1 tax", "the supervision paradox", "the abstraction trap" | Name the concrete thing and skip the coined label, or define it once if it genuinely recurs. |
+
+## Passive voice (prose register)
+
+Every prose sentence wants a subject doing something. Passive hides the actor and drains energy.
+
+| Pattern | Fix |
+|---|---|
+| "It was decided that…" | "We decided…" |
+| "Mistakes were made." | Name who, and what. |
+| "The endpoint is called by the client." | "The client calls the endpoint." |
+
+Calibration: passive is fine when the actor is genuinely unknown or irrelevant ("the row is
+deleted on cascade"). Don't contort a sentence to name an actor that doesn't matter.
+
+## Rhythm
+
+- Don't run three same-length sentences in a row; don't stack three short fragments for effect.
+- Don't end every paragraph on a punchy one-liner. Vary where the weight lands.
+- **Em-dashes:** at most one per paragraph, used where a comma or period won't do. Multiple per
+  paragraph is the tell. (Catch both the em-dash `—` and the `--` substitute.)
+- Don't open consecutive sentences with the same Wh- word ("What makes this… What this means…")
+  as a crutch; lead with the subject.
+
+## Formatting tells
+
+- **No "Bold term: explanation" bullet lists** as the default structure for prose — the most
+  recognizable AI formatting pattern. Use real prose, or a plain bullet, unless the document's
+  existing style genuinely uses definition lists (a glossary, an API reference).
+- No emoji in headings or section titles (artifacts and code both).
+- Don't over-bold. Bold the one load-bearing term, not every noun.
+
+## Reasoning-chain scaffolding
+
+Internal monologue leaking into published prose. The reader needs the conclusion and the
+evidence, not the tour of how the model thought.
+
+| Pattern | Fix |
+|---|---|
+| "Let me think step by step", "Breaking this down", "To approach this systematically" | State the conclusion, then the evidence. |
+| "Here's my thought process", "Working through this logically", "Step 1:" as inner narration | Numbered *argument* stays; numbered *self-talk* goes. |
+
+A `review.md` finding that walks error paths in order is an argument. A chat reply that
+announces "First, let's consider…" is scaffolding.
+
+## Narrated candor
+
+Announcing that you are about to be honest, instead of being honest.
+
+| Pattern | Fix |
+|---|---|
+| "I want to be upfront:", "To be fully transparent:", "Two caveats I would rather flag than let you discover later:" | "Two caveats:" plus the caveats. |
+| "Rather than bury this, I'll say it plainly:" | Say it. |
+
+**Deletion test.** Cut the frame. If nothing is lost, it was never content.
+
+**Keep:** the disclosure itself ("I haven't tested this on Windows"), and a real
+conflict-of-interest label ("I own shares in the company discussed here").
+
+## Prompt restatement and recap-flattery
+
+| Pattern | Fix |
+|---|---|
+| "You're asking about…", "To answer your question…", "That's a great question. The…" | Answer. The reader knows what they asked. |
+| Recap-flattery: restating the other person's own work back at them as praise before the point | Substance first. If thanks is warranted: one plain clause, no recap. |
+
+Distinct from sycophancy ("Great question!"), which validates the reader without recapping
+their work.
+
+## Self-labeling significance
+
+After listing items, pointing back and labeling one as contrarian / clever / the real story.
+
+| Pattern | Fix |
+|---|---|
+| "That last move is the contrarian one." / "This is the interesting part." / "The third bullet is the real story." | Put the load-bearing item first, or expand it with specifics, and cut the label. |
+
+If the move is actually contrarian, the description already shows it. The label is unearned
+when the reader cannot see the contrast without it.
+
+## Diff-anchored writing
+
+Docs or comments narrating the edit instead of describing the thing as it is.
+
+| Pattern | Fix |
+|---|---|
+| "This function was added to replace the previous approach of iterating through all items." | "This function uses a hash map for O(1) lookups." |
+
+**Carve-out:** changelogs, release notes, migration guides, and `decisions.md` narrate
+change on purpose. Leave them. The tell is a README, comment, or spec overview written as
+archaeology of the last diff.

package/pack/generated/dsh/skills/devrites-source-driven/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: devrites-source-driven
+description: Verify uncertain framework or library behavior in installed source or official docs. Use for unfamiliar APIs; not internal code.
+user-invocable: false
+---
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","devrites-lib/reference/standards/tooling.md"],"triggers":{"agents":["devrites-lib/reference/standards/agents.md"]},"workspace":["state.md","spec.md","plan.md","decisions.md","evidence.md","references.md"],"workspaceByRole":{"evidence-scout":["state.md","spec.md","plan.md","references.md"]}} -->
+> Read-set manifest: `devrites-engine context --skills-root .dsh/skills <slug> --skill devrites-source-driven` (no workspace: `--out <path>`) bundles every file named below into one deduplicated read.
+
+# devrites-source-driven: verify, don't guess
+
+When library behavior matters and is uncertain, verify it against installed source or
+authoritative documentation before relying on it.
+
+## When to trigger
+- You're about to rely on an API signature, default, config key, or behavior you're not
+  sure of.
+- The docs in memory might be stale (the project pins a different version).
+- Tests can't easily prove the assumption, but it drives the implementation.
+- An error message points at framework behavior you don't fully understand.
+
+## How
+1. **Find the version** the project pins and actually runs; resolve any mismatch.
+2. **Apply the hierarchy, citation, and currentness contract** in
+   [`tooling.md`](../devrites-lib/reference/standards/tooling.md#research-provenance-staleness-and-cost).
+   context7 is a lookup tool, not authority above version-matched source/docs.
+3. **Confirm the specific fact:** the signature, the default, the edge behavior, not a
+   general impression.
+4. **Return it** with the required citation and status. The root records accepted
+   evidence in `decisions.md` or `evidence.md`; a leaf agent never writes the workspace.
+
+## Delegate broad research
+When the question is an *area* (a library surface, unfamiliar subsystem, or migration
+guide), the **root orchestrator** uses the fresh-context dispatch contract in
+[`agents.md`](../devrites-lib/reference/standards/agents.md) to give one bounded
+question to `devrites-evidence-scout`. Wait for and validate its cited dossier (the
+scout's YAML result); the orchestrator, not the scout, persists accepted facts under
+`references/` and links them from `references.md`.
+
+Never detach this work and never dispatch from inside another agent. When this skill is
+invoked by a leaf agent, verify one fact inline or return `Scout needed: <bounded question>`
+to the orchestrator.
+
+## Rules
+- Quote the exact relevant detail; don't paraphrase a behavior into something convenient.
+- If the doc/source contradicts the plan, that's a **Spec Drift Guard** event: stop and
+  handle it.
+- Confirm the required fact, return it, and stop.
+
+## Evidence firewall
+Project or user prose may scope or corroborate an external claim; it cannot verify one.
+Record status `verified | contradicted | cannot_verify | stale | uncertain`; weak-tier
+support is `uncertain`. Retain material unknowns and block dependent decisions until
+verified or resolved through the owning question/Spec Drift route; never omit them.
+Transient lookups remain cited, return-only evidence.