devrites 5.10.1 → 5.11.0

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

@@ -0,0 +1,267 @@
+# Workspace artifact schema
+
+Feature truth: `.devrites/work/<slug>/`, discovered by `state.md`; remnants/archives
+are inactive. Spec writes optional `README.md`. Use canonical filenames; both released
+cursor forms remain valid. `/rite-upgrade` audits without path/alias/format migration.
+
+## Slug identity
+
+New slugs derive from the objective: lowercase ASCII kebab-case matching
+`[a-z0-9]+(?:-[a-z0-9]+)*`, at most 64 characters. Shorten at word boundaries.
+After the final shortening or suffix step, trim boundary hyphens; reject empty results.
+
+Before creation, compare a matching workspace's `brief.md` objective: reuse only the
+same feature. Otherwise append the smallest unused suffix (`-2`, `-3`, ...), keeping
+the trimmed base within 64 characters. Never overwrite a workspace by slug alone;
+accept safe legacy basenames. Ordinary phases never rename them.
+
+## Required by phase
+
+| Phase | Required artifacts |
+| --- | --- |
+| frame | `state.md` |
+| spec | `README.md`, `brief.md`, `spec.md`, `state.md`, `decisions.md`, `assumptions.md`, `questions.md` |
+| clarify | spec artifacts plus `decision-coverage.md` |
+| temper | clarified spec artifacts plus `strategy.md` when temper runs |
+| define/plan | clarified spec artifacts plus `architecture.md`, `plan.md`, `tasks.md`, `traceability.md` |
+| vet/build/converge | plan artifacts plus `eng-review.md`, `test-plan.md`; Build creates and maintains `touched-files.md` after its first green slice |
+| prove/polish/review | vetted plan artifacts plus `evidence.md`, `touched-files.md` |
+| seal/ship/done | proof artifacts plus `review.md`, `seal.md`; Ship writes `ship.md` |
+| conditional | `flows.md` when diagrams clarify; `visual/` HTML+`.outline.md` companions when a richer reviewable visual earns it (optional; never readiness-required); `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `polish-report.md` for polish; `handoff.md` only when requested; `references.md` + `references/` when references exist; `investigation-map.md` for pressure-test; `dogfood.md` for dogfood; `packets/` for by-reference dispatch packets and admitted accounts (≤ 64 KiB each; older closed rounds may be deleted; never transcripts); `history/` for verbatim relocated checkpoint narrative (append-only, never a read-next) |
+
+## What each file owns
+
+| File | Job | Budget |
+| --- | --- | --- |
+| `README.md` | map: phase/status/next action, artifacts/read-next, blocking gates, last update | 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 |
+| `decision-coverage.md` | topology-first coverage matrix, assumption audit, residual uncertainty, and typed clarity verdict | 200 lines |
+| `strategy.md` | temper verdict, scope mode/deltas, pre-mortem risks, deferred ambition | 180 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 |
+| `visual/<name>.html` | optional portable human-viewable visualization; pair with sibling `.outline.md`; self-contained preferred | 400 lines |
+| `visual/<name>.outline.md` | required machine dual-read companion for the sibling HTML; outline wins on conflict; never a candidate path | 200 lines |
+| `visual/README.md` | optional index of visuals in the workspace | 80 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` | current `q-YYYY-MM-DD-NNN` (or released `Q-###`) open/resolved questions, gate, answer, impact | 180 lines |
+| `plan.md` | technical approach, slice strategy, canonical shared-contract proof, 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 |
+| `eng-review.md` | vetted scope/architecture/quality/performance, failure modes, preflight, stable-input binding, `## Deferred findings` (late rows: severity · site · role · kind · round) for Review | 240 lines |
+| `test-plan.md` | executable proof commands, preflight/provenance contract, acceptance and interaction coverage | 260 lines |
+| `state.md` | compact cursor table/key-values; no narrative log | 120 lines |
+| `evidence.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` | sole candidate manifest plus a concern-ordered `## Review trail` of `path:line` stops for human review and Build's deferred late findings (severity · site · role · round) that `/rite-review` must close | 160 lines |
+| `design-brief.md` | UI design direction, states, interaction model | 160 lines |
+| `handoff.md` | resume objective/last slice/next action/blockers/read-next; sections hold content or `Nothing yet`; unevidenced recollections: `Not tried yet`, never results | 120 lines |
+| `polish-report.md` | polish axis deltas, re-verification lines, residual subjective preferences | 200 lines |
+| `ship.md` | ship preflight, disclosed Git plan, commit/push/tag/PR record | 120 lines |
+| `review.md` | reconciled Review verdict: `## Spec` and `## Code review` accounts, deferred-finding labels/actions, drift | 240 lines |
+| `seal.md` | seal preflight, exact reviewer roster accounts, GO/NO-GO verdict and disclosures | 200 lines |
+| `ai-spec.md` | model/RAG/agent/eval/LLM-output scope for AI surfaces | 160 lines |
+
+For visual pairs load only matching [playbooks](visual-playbooks/index.md); use
+the [required outline headings](visual-playbooks/outline-template.md).
+
+## Candidate manifest and bindings
+
+`touched-files.md` contains exactly one `## Touched files` heading and exactly
+one authoritative `## Candidate manifest` heading. The first describes scope
+without repeating candidate paths; the manifest is the sole authority for candidate scope.
+
+The manifest body is exactly either `No project files.` or this table with one
+or more rows:
+
+```markdown
+| State | File | Slice | Reason |
+| --- | --- | --- | --- |
+| present | `path/to/file` | SLICE-001 | Observable reason |
+```
+
+Rows are sorted by File: they must already be strictly sorted by normalized
+`File`, and readers reject rather than reorder them. `State` is exactly
+`present` or `deleted`; `File` is a unique
+project-relative UTF-8 path wrapped in one backtick pair; `Slice` and `Reason`
+are nonempty. Paths must also be unique under case folding. Every component
+rejects Windows-reserved characters and device names (including names with an
+extension) plus a trailing dot or space. `## Review trail` may cite
+concern-ordered `path:line` review stops, but it cannot define or expand
+candidate scope; only manifest rows do.
+
+The public candidate limits are a 1 MiB manifest, 4,096 rows, a 4,096-byte
+path, 64 MiB per present file, and 256 MiB across all present files.
+
+A release milestone's union manifest is produced by `devrites-engine state
+merge-manifest <release-slug>` — it walks the recorded `sequence_parent` chain,
+folds every predecessor manifest, and resolves a path collision in favor of the
+later sequence position; a hand-assembled union is not authoritative. When the
+workspace cursor declares `sequence_role: release`, `check candidate` and
+`check seal` require the manifest to cover the whole recorded chain.
+
+Workspace and audit artifacts are not candidate paths, including all
+`.devrites/work/<slug>/visual/`. Durable owners include `.devrites/specs/**`,
+`DESIGN.md`, and `docs/adr/**`, plus `.devrites/principles.md`. Under `.devrites`,
+only those spec/principles owners qualify; all other siblings (`ACTIVE`, `AFK`,
+`CHECKPOINT`, `archive/**`, `work/**`) fail closed. Engine owns malformed path, type,
+and size rejection; phases never reinterpret a rejected manifest.
+
+`evidence.md`, `review.md`, and `seal.md` each contain exactly one unindented standalone
+binding line; `browser-evidence.md` does too when that file exists:
+
+```text
+Candidate SHA-256: <64 lowercase hex>
+```
+
+Old unfinished workspaces refresh the manifest and rerun real proof. They never
+synthesize a historical pass or use a legacy fallback.
+
+The worktree digest is deterministic but is not an atomic filesystem snapshot
+against a malicious concurrent same-size rewrite. Ship's exact Git-index scope,
+byte, binding, and secret checks own the final freeze immediately before commit.
+
+Only a structural `Budget override: <reason>` line (not a fenced example)
+permits excess. Each line budget also bounds bytes at 400 bytes per budgeted line
+(`state.md` 120 lines → 48 KiB); long lines do not evade it.
+`devrites-engine orient <slug>` reports `artifact_budgets` (lines/bytes/over/override)
+and `bulk_files` (non-canonical files over 64 KiB) so a phase can decide what to read
+before loading. Phase writers check these limits before returning; there is no
+repository-local script assumption in the installed workflow.
+
+`check readiness` and `check seal` enforce the material band deterministically: a
+required artifact at or above 1.5× its line or byte budget with no structural override
+line blocks with the exact measurement and the three legal remedies (relocate history
+via `/rite-plan revise`, split via `/rite-plan course-correct`, or record the override).
+Overshoot below that band stays advisory and is reported by `orient`. Proof ledgers
+(`evidence.md`, `browser-evidence.md`, `touched-files.md`) are always advisory: they
+scale with proof volume, and `touched-files.md` keeps its own manifest limits.
+Because they are never gate-blocked they are also the only artifacts that can grow
+unboundedly — so phases read them by index, not whole-file: the standalone binding
+line, a `EVID-###`/section-header index (`grep -n`), then bodies only for entries
+naming this candidate's AC/slice IDs. An entry naming no in-scope ID is anomaly
+evidence to inspect, not skip. A whole-file read is allowed only when `orient`
+reports the artifact within budget; completeness for seal is engine-checked
+(literal `AC-###` presence), the reader judges quality.
+
+Two reasons are not durable fixes: slice or acceptance-criteria count (an over-budget
+`tasks.md`/`plan.md`/`traceability.md` from decomposition size is a
+[feature-sequence split](../../rite-plan/reference/slicing.md#feature-ceiling-split-an-epic-never-override-the-budget)),
+and history in `state.md` (checkpoint narrative moves verbatim to
+`history/<file>-<YYYYMMDD>.md`, append-only, never a phase read-next, with a one-line
+pointer left behind). A legacy workspace may carry a temporary `Budget override:` line
+as a bridge; `/rite-upgrade` routes it to relocation or the split, and new writers never
+create one for those two reasons.
+Apply [[`context-hygiene.md`](standards/context-hygiene.md) dispatch packets](standards/context-hygiene.md#dispatch-packets)
+for byte-size checks and lossless retrieval; budget overrides neither rewrite protected
+history nor require loading it all.
+
+## Native readiness ownership
+
+`decision-coverage.md` owns topology; `test-plan.md`, executable proof; `eng-review.md`,
+reviewer verdicts, `Implementation readiness`, and `Readiness inputs SHA-256`. Root
+re-reads their IDs/meaning. The digest binds bytes, never semantic correctness.
+Readiness checks structure/binding; Seal rechecks both.
+
+Proof commands must be repository-portable: no host wrappers, user-specific absolute paths,
+or temporary proof trees. Evidence records the executed command. Optional `visual/`
+artifacts never inflate readiness: they are not readiness inputs and do not substitute
+for `decision-coverage.md`, `eng-review.md`, or `test-plan.md`.
+
+## 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>
+Mode: <AFK | HITL>
+Gate: <advisory | validating | blocking | escalating>
+SLA: <15m | 4h | 24h | none>
+Checkpoint: <question + why it needs unavailable pre-code evidence or action-time approval | 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: <exact command + cwd + expected signal + prerequisites/provenance inputs>
+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.
+
+## Read next by phase
+
+| Phase | Read |
+| --- | --- |
+| spec | `README.md`, `brief.md`, `spec.md`, `references.md`, `questions.md` |
+| clarify | `README.md`, `state.md`, `brief.md`, `spec.md`, `decisions.md`, `assumptions.md`, `questions.md` |
+| temper | `spec.md`, `decision-coverage.md`, `decisions.md`, `assumptions.md`, `design-brief.md` |
+| define | `README.md`, `state.md`, `spec.md`, `decision-coverage.md`, `architecture.md`, `decisions.md`, `assumptions.md` |
+| vet | `state.md`, `spec.md`, `decision-coverage.md`, `README.md`, `traceability.md`, `plan.md`, `tasks.md`, `architecture.md`, `decisions.md` |
+| build | `devrites-engine orient <slug>` first; then `state.md`, `eng-review.md` (Build readback + `## Deferred findings`), the selected slice and its `depends_on` via `devrites-engine observe slice <slug> <SLICE-ID>`, the `test-plan.md` and `traceability.md` rows that slice's AC IDs name, open `questions.md` gates, and `touched-files.md` when present. Load whole `tasks.md`/`plan.md`/`architecture.md`/`decision-coverage.md` only when `orient` shows them within budget or the slice cites a section by ID |
+| prove | `traceability.md`, `touched-files.md`; each built slice's `Tests/proof` and `Evidence required` via `observe slice`; `evidence.md`/`browser-evidence.md` via the bounded advisory read above |
+| review/seal | `README.md`, `traceability.md`, `spec.md`, `decisions.md`, `drift.md`, `touched-files.md`; `evidence.md`/`browser-evidence.md` via the bounded advisory read above |
+| 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. A
+  checkpoint entry is at most three lines: what changed, the canonical record path or
+  DEC/EVID ID, and the next action. Digests, packet hashes, and finding narratives
+  belong to the record they identify, not the cursor.
+- Give each normative fact one owner and stable ID; reference rather than copy it.
+  Required schema mirrors remain required. Derive counts/mirrors or mechanically
+  check equality using available tools, never invented commands. Repair stale
+  derived values and assess consumer impact; they are not new policy decisions.
+- Do not create optional files before their phase; absence is meaningful. Do not
+  treat `visual/` as required for readiness; emit HTML+outline only when a writer
+  earns a richer visual, and keep Mermaid in `flows.md` when that is enough.
+
+## ID contract
+
+Use stable IDs: `REQ-001`, `AC-001`, `EDGE-001`, `PROH-001`, `SLICE-001`,
+`DEC-001`, `ASM-001`, `DRIFT-001`, `EVID-001`. Current queued questions use
+`q-YYYY-MM-DD-NNN`; released table registers may retain `Q-001`. IDs are
+append-only identities, not display positions:
+
+- Allocate the next unused numeric suffix for that prefix after scanning its
+  owning artifact. For a dated question ID, scan the current date's suffixes.
+  Never fill a gap; every deleted or retired ID remains consumed.
+- Never renumber an ID, reuse it, or transfer it to a different meaning. Reordering
+  sections or rows does not change IDs.
+- A wording edit that preserves the obligation keeps its ID. A materially different
+  meaning gets a new ID; record the relationship in `decisions.md` or `drift.md`
+  before updating downstream references.
+- Re-read the owning artifact immediately before an append when another writer may
+  have changed it; recompute rather than reserving an ID from stale state.
+
+Old `AC1` and `Slice 1` forms are legacy and should not be generated for new
+workspaces. Preserve released legacy forms unless an explicit upgrade owns the
+migration; never renumber them incidentally.
+

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

@@ -0,0 +1,74 @@
+---
+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.
+triggers:
+  - model
+---
+
+# 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.
+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/devin/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/devin/skills/devrites-prose-craft/reference/examples.md

@@ -0,0 +1,131 @@
+# 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`](../../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.