devrites 2.6.1 → 3.0.0

package/pack/generated/claude/skills/devrites-lib/reference/workspace-artifact-schema.md

@@ -0,0 +1,110 @@
+# Workspace artifact schema
+
+DevRites stores feature truth in `.devrites/work/<slug>/`. The older
+`.devrites/features/<slug>/` path remains readable during migration; do not delete
+existing workspaces or aliases. `feature.md` and `index.md` may stand in for the
+workspace map; `proof.md` may stand in for `evidence.md`.
+
+## Required by phase
+
+| Phase | Required artifacts |
+| --- | --- |
+| spec | `README.md`/`index.md`/`feature.md`, `brief.md`, `spec.md`, `state.md`, `decisions.md`, `assumptions.md`, `questions.md` |
+| define/plan/vet/build | spec artifacts plus `architecture.md`, `plan.md`, `tasks.md`, `traceability.md` |
+| prove/polish/review/seal/ship | plan artifacts plus `evidence.md`/`proof.md`, `touched-files.md` |
+| conditional | `flows.md` when diagrams clarify; `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `handoff.md` only when requested; `references.md` + `references/` when references exist |
+
+## What each file owns
+
+| File | Job | Budget |
+| --- | --- | --- |
+| `README.md` / `index.md` / `feature.md` | compact workspace map: phase, status, next action, artifact map, read-next table, blocking gates, last updated | 120 lines |
+| `brief.md` | user request, objective, non-goals, success definition | 80 lines |
+| `spec.md` | product WHAT/WHY, requirements, acceptance criteria, edge cases, measurable success, scope boundaries | 260 lines |
+| `architecture.md` | owning layer, integration points, data/API/events, dependencies, risks, affected boundaries | 180 lines |
+| `flows.md` | useful Mermaid sequence/state/data/lifecycle diagrams with why-it-matters text and related IDs | 160 lines |
+| `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs | 200 lines |
+| `assumptions.md` | assumptions with confidence, owner, validation status | 160 lines |
+| `questions.md` | `Q-###` open/resolved questions, gate, answer, impact | 180 lines |
+| `plan.md` | technical approach, slice strategy, validation strategy, rollback | 220 lines |
+| `tasks.md` | `SLICE-###` vertical slices with AC IDs, likely files, tests/proof, mode/gate, dependencies, done condition | 280 lines |
+| `traceability.md` | matrix: AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status | 220 lines |
+| `state.md` | compact cursor table/key-values; no narrative log | 120 lines |
+| `evidence.md` / `proof.md` | `EVID-###` command/action, result, timestamp if available, related AC/slice IDs, limitation | 280 lines |
+| `browser-evidence.md` | UI route/viewports/screenshots/console/network/interactions and Visual Verdict | 220 lines |
+| `drift.md` | `DRIFT-###` spec/plan drift and resolution | 160 lines |
+| `touched-files.md` | implementation files, slice ownership, reason, and a concern-ordered `## Review trail` of `path:line` stops for human review | 180 lines |
+| `design-brief.md` | UI design direction, states, interaction model | 160 lines |
+| `handoff.md` | cold-resume guide: current objective, last completed slice, next action, blockers, read-next links | 120 lines |
+
+Files can exceed the budget only with `Budget override: <reason>`.
+
+## Canonical slice grammar
+
+Every producer of `tasks.md` uses this field set. `Dependencies` is slice
+ordering; package and service requirements belong in `External dependencies`.
+
+<!-- canonical-slice:start -->
+```markdown
+## SLICE-001 <observable capability>
+Goal: <single observable capability>
+Satisfies: AC-001[, AC-002]
+Acceptance criteria: <binary criteria this slice closes>
+Complexity: <1..5> — <reason>
+Forge: <no | yes — reason>
+Mode: <AFK | HITL>
+Gate: <advisory | validating | blocking | escalating>
+SLA: <15m | 4h | 24h | none>
+Checkpoint: <question | none>
+Dependencies: <SLICE-### list | none>
+depends_on: [<SLICE-### IDs>]
+Consumes / Produces: <interfaces read and exposed>
+Known-Gotchas: <ordering hazards and framework footguns | none>
+Prior-slice learnings: <constraints learned earlier | none>
+Files likely touched: <real paths>
+Tests/proof: <tests to write/run and exact validation commands>
+Browser proof required: <yes | no>
+Frontend craft required: <yes | no>
+Design brief states: <UI states/interaction | none>
+Visual acceptance: <state × viewport × input target | none>
+Fullstack (FE+BE): <yes | no>
+External dependencies: <libraries/services | none>
+Existing to reuse / extend: <components/utilities/patterns | none>
+Rollback notes: <reversal path>
+Evidence required: <evidence /rite-prove must capture>
+Edge/Prohibition coverage: <EDGE/PROH IDs | none>
+Done condition: <checkable, exhaustive completion criterion>
+```
+<!-- canonical-slice:end -->
+
+`depends_on` is the machine-readable mirror of `Dependencies`; keep the sets
+identical and cycle-free. `Gate`, `SLA`, and `Checkpoint` are required for HITL
+slices; use `none` when they do not apply. Complexity above 3 triggers reslicing
+unless the stated reason makes the boundary irreducible. `Forge: yes` is reserved
+for a high-complexity architecture fork with multiple viable approaches.
+
+## Read next by phase
+
+| Phase | Read |
+| --- | --- |
+| spec | `README.md`, `brief.md`, `spec.md`, `references.md`, `questions.md` |
+| define | `README.md`, `state.md`, `spec.md`, `architecture.md`, `decisions.md`, `assumptions.md` |
+| vet | `README.md`, `traceability.md`, `plan.md`, `tasks.md`, `architecture.md`, `decisions.md` |
+| build | `state.md`, `tasks.md`, `plan.md`, `architecture.md`, `traceability.md`, `questions.md` |
+| prove | `traceability.md`, `tasks.md`, `evidence.md`, `browser-evidence.md`, `touched-files.md` |
+| review/seal | `README.md`, `traceability.md`, `spec.md`, `evidence.md`, `decisions.md`, `drift.md`, `touched-files.md` |
+| handoff | `README.md`, `state.md`, `handoff.md`, then the linked source artifacts |
+
+## Do not duplicate
+
+- Do not make `spec.md` carry deep architecture; link to `architecture.md`/`flows.md`.
+- Do not copy acceptance criteria into `plan.md`; reference `AC-###`.
+- Do not copy full proof into `handoff.md`; link to `evidence.md`.
+- Do not make `state.md` an append-only log; keep only the current cursor.
+- Do not create optional files before their phase; absence is meaningful.
+
+## ID contract
+
+Use stable IDs: `REQ-001`, `AC-001`, `SLICE-001`, `DEC-001`, `Q-001`,
+`DRIFT-001`, `EVID-001`. Old `AC1` and `Slice 1` forms are legacy and should
+not be generated for new workspaces.

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

@@ -0,0 +1,69 @@
+---
+name: devrites-prose-craft
+description: Humanize prose without losing technical content. Use when asked to remove AI-writing tells, match a writing sample or project voice, edit artifacts/replies/commit or PR prose, or run `/rite-polish`'s prose pass. Not for code comments or UI craft.
+user-invocable: false
+---
+
+# 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 a substantive **user-facing reply** (not the deterministic progress
+  footers — those are script-rendered and exact by design).
+- `/rite-polish` Phase 1 as the **catch** pass on prose that slipped through at write time.
+
+## 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 — a user's existing
+  `spec.md` at `/rite-adopt`, 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) → **P1** obvious tells (negative
+parallelism, filler openers, em-dash tics) → **P2** polish (rhythm, word choice). A quick pass
+fixes P0 + P1 and stops; a full pass takes P2 too.
+
+## 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.
+   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.
+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. Done when the preservation contract passes, the technical register remains exact,
+   and no in-scope tell remains.
+
+## 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.
+- 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/claude/skills/devrites-prose-craft/reference/banned-phrases.md

@@ -0,0 +1,95 @@
+# 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"
+
+## 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"
+
+A `decisions.md` entry or a `seal.md` verdict is a document, not a chat turn. No pleasantries.
+
+## 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. Three tiers:
+
+**Tier 1 — always slop, replace on sight (figurative filler, never load-bearing in a spec):**
+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 2 — slop in prose, legitimate in technical context (keep the meaning, judge by use):**
+robust, comprehensive, seamless, leverage, harness, facilitate, underpin, streamline,
+foster, utilize, 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/claude/skills/devrites-prose-craft/reference/examples.md

@@ -0,0 +1,102 @@
+# 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):**
+> It's worth noting that the error handling here could potentially be more robust. This is a
+> critical area that fundamentally matters for production readiness.
+
+**After:**
+> Critical — `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.
+
+Severity label, `file:line`, the specific problem, the fix. No hedging, no "fundamentally".
+
+## 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: slice 4 (pagination). Want me to continue?
+
+Dropped the pleasantries and the "not just X" inflation. Led with what's done and the evidence.
+
+## 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`: 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.
+
+## The pattern across all seven
+
+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") and importance labels ("pivotal").
+4. Keep the technical register intact: exact identifiers, status codes, numbered criteria,
+   real enumerations. Precision is not slop.

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

@@ -0,0 +1,134 @@
+# 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. |
+
+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. |
+
+## 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.

package/pack/generated/claude/skills/devrites-refresh-indexes/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: devrites-refresh-indexes
+description: Refresh stale optional indexes. Use when structural lookup disagrees with live code or rite-doctor requests a synchronous reindex.
+user-invocable: false
+---
+
+# devrites-refresh-indexes — keep the code-intelligence indexes fresh
+
+`tooling.md` says to cross-verify structural claims across codebase-memory-mcp, codegraph, and
+graphify, and that **a disagreement between indexes is a signal** — a fresh read of live code
+beats any index. A *stale* index manufactures exactly that disagreement. This keeps the three
+mechanical indexes current after edits so the next lookup is trustworthy.
+
+All three are **optional** (per `tooling.md`): each is refreshed only if its binary is on PATH
+**and** it already tracks this repo. None present → this is a silent no-op. Never installs
+anything, never blocks. Same incremental shape for all three; no LLM needed for code.
+
+| Index | Tracks repo when | Refresh |
+|---|---|---|
+| **codebase-memory-mcp** (primary) | binary present + repo in `list_projects` (or `.codebase-memory/`) | `codebase-memory-mcp cli index_repository '{"repo_path":"<root>"}'` |
+| **codegraph** | `.codegraph/` exists + `codegraph` on PATH | `codegraph sync` |
+| **graphify** | `graphify-out/` exists + `graphify` on PATH | `graphify update .` |
+
+## Automatic (already wired — no action needed)
+
+The `Stop` hook `devrites-engine hook refresh-indexes` runs at end of turn. It self-guards: exits
+instantly unless an index tracks the repo, exits instantly if no source file changed since the
+last refresh, else stamps + locks and spawns a **detached** worker so the turn never blocks.
+ON by default; disable with `DEVRITES_REFRESH_INDEXES=off`.
+
+## Manual / thorough refresh (this skill)
+
+Force a synchronous refresh now and print the report — resolve the hook across install layouts:
+
+```bash
+devrites-engine hook refresh-indexes --force .
+```
+
+Then the one case the hook can't cover:
+
+- **Docs / papers / images changed** (not just code) → `graphify update` only re-runs AST. Run
+  the full semantic re-extraction: `/graphify --update` (re-extracts only changed files).
+
+## Notes
+
+- codegraph and codebase-memory-mcp each have their own background watcher; the explicit
+  reindex is the belt-and-suspenders fallback for when a watcher isn't running. graphify has no
+  default watcher, so this is its primary freshness path.
+- The index lags writes by ~1s after a refresh — don't re-query in the same instant you edit.
+- Output hygiene (`prose-style.md`): don't name these tools to the user — say what changed
+  ("re-indexed the edited files"), not which tool did it.

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

@@ -0,0 +1,52 @@
+---
+name: devrites-source-driven
+description: Verify uncertain framework/library behavior against official docs or installed source before relying on it. Use when the user says "check the docs", "verify this assumption", or hits an unfamiliar API. Not for internal code.
+user-invocable: false
+---
+
+# devrites-source-driven — verify, don't guess
+
+A confident wrong assumption about a library is a bug waiting to ship. When behavior
+matters and isn't certain, check the source of truth.
+
+## 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 actually uses (lockfile, manifest) — behavior is
+   version-specific.
+2. **Consult the source of truth**, in order: the installed package's own source/types
+   in `node_modules`/gem/site-packages; context7 if available (`resolve-library-id` →
+   `query-docs`) for current upstream docs; official docs for *that version*; the project's
+   existing usage of the same API.
+3. **Confirm the specific fact** — the signature, the default, the edge behavior — not a
+   general impression.
+4. **Record it** in `decisions.md` (or `evidence.md`): the fact, the version, and the
+   source (path or URL). Future phases trust the record instead of re-checking.
+
+## Delegate reading legwork bigger than one fact
+When the question is an *area*, not a fact — surveying a library's API surface, an unfamiliar
+subsystem's docs, a migration guide — dispatch a **background agent** instead of reading inline:
+it investigates against the same source-of-truth order above, cites each claim (path or URL +
+version), and writes one note to the active workspace's `references/` directory, linked from
+`references.md`. You keep working while it reads; later phases trust the cited note. The inline
+flow above stays the path for confirming a single fact.
+
+## Rules
+- Prefer the **installed** source over remembered docs — it can't be out of date.
+- 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.
+- Don't rabbit-hole: confirm the one fact you need, record it, return.
+
+## Re-fetching is cheap (and still fresh)
+Fetching the same doc URL twice costs almost nothing: on Claude Code a WebFetch is transparently
+cached per project and, on reuse, revalidated against the origin — the cached reading is replayed **only**
+when the server confirms the page is unchanged (HTTP 304). A 304 is a fresh verification, not a
+memory read, so citing a revalidated page is as sound as re-fetching it. Fetch freely; don't
+skip a check to save a round trip. (Mechanism: the `devrites-source-cache` hooks; off via
+`DEVRITES_SOURCE_CACHE=off`. Web-search + cache policy lives in [`tooling.md`](../devrites-lib/reference/standards/tooling.md).)