devrites 5.10.2 → 5.11.0

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.

package/pack/generated/devin/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/devin/skills/devrites-source-driven/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: devrites-source-driven
+description: Verify uncertain framework or library behavior in installed source or official docs. Use for unfamiliar APIs; not internal code.
+triggers:
+  - model
+---
+
+# 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.

package/pack/generated/devin/skills/devrites-ux-shape/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: devrites-ux-shape
+description: Shape UX/UI direction, states, and interactions before code. Use for screens, forms, dashboards, or settings; not for implementation or polish.
+triggers:
+  - model
+---
+
+# devrites-ux-shape: plan the UX/UI before code
+
+Decide what the UI *is* and how it should look and behave **before** code, and write it to
+the feature's `design-brief.md`: the contract the build (`devrites-frontend-craft`),
+polish, and seal all check against. This is "shape before code" raised to a **feature-level
+artifact**: produced once at spec time, refined per slice. It is **woven into the
+lifecycle** (`/rite-spec` calls it when UI is detected; `/rite-build` refines it), not a
+separate phase the user runs.
+
+## When it runs
+- `/rite-spec` invokes it after references-intake when the feature touches UI
+  (`../rite-build/reference/frontend-trigger.md`). Output: `design-brief.md` + a
+  confirmation pause.
+- `/rite-build` / `devrites-frontend-craft` read the brief as the **build target** and
+  refine it for the slice's surface. They don't re-derive it.
+- Skip entirely for backend / data / CLI / infra-only features.
+
+## 1. Foundation: discover, don't impose
+Reuse what's there first. Read the design system + register and any references the spec
+gathered:
+- Design system + register (tokens, components, type, spacing, neighbors; brand-vs-product)
+  → `../devrites-frontend-craft/reference/design-references.md`.
+- `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` if present: anchors that reduce questions.
+  `DESIGN.md` is the rolled-up design memory (`../rite-polish/reference/design-memory.md`;
+  see `../devrites-frontend-craft/reference/design-references.md`) — read it before
+  re-discovering, depart only on signal.
+- `references.md` + `references/`: the screenshots / Figma / video / links the human
+  supplied. Honor each recorded role: **target** = fidelity contract, **constraint** =
+  required rule, **inspiration** = extract only the cited principle.
+
+## 2. Discovery: one round, assert-then-confirm
+Understand the feature deeply enough to make excellent design calls: **no code, no
+markup**. Use the `devrites-interview` cadence: one question per turn (≤3 per pass),
+best-guess attached, stop when answers converge. One round is the default; add a second only for
+material gaps. When `PRODUCT.md` + the spec already pin an answer, **assert it and ask to
+confirm** ("reads as Restrained: confirm?"), don't offer a four-option menu. Cover:
+- **Purpose & user:** who, in what state of mind (rushed / exploring / anxious / focused).
+- **Content & data:** realistic ranges (0 / typical / many), dynamic content, real
+  media/assets the surface needs.
+- **Preserve + anti-goals:** identity, IA, behavior, content voice, SEO/analytics hooks,
+  existing accessibility wins, or assets that must survive; what this must NOT become;
+  the biggest risk of getting it wrong.
+
+## 3. Design direction: the direction set (commit, don't hedge)
+One deliberate visual decision on five fronts, each anchored in an existing reference so
+the call is checkable, not taste:
+- **Scene sentence:** who / where / ambient light / mood, per
+  `../devrites-frontend-craft/reference/design-references.md`. Forces dark-vs-light and
+  tone from the scene, not the category.
+- **Color strategy:** Restrained / Committed / Multi-role / Saturated, per the
+  color-commitment table in `../devrites-frontend-craft/reference/quality-standards.md`.
+  Pick from the scene; register doesn't decide it.
+- **Calibration:** density (Airy / Balanced / Dense) and motion (Minimal / Standard /
+  Expressive), per the calibration table in the same quality-standards file. Set both from
+  the scene so the build targets a calibration, not a guess (a 2am SRE → Dense + Minimal; a
+  launch hero → Airy + Expressive).
+- **Named anchor references:** 2-3 *specific* products / brands / objects to steer toward
+  (not adjectives like "modern" or "clean"), plus the saved `references/` files.
+- **Visual thesis:** the focal point and hierarchy in one sentence, plus one memorable
+  move (or `none — system continuity`) and the obvious-but-wrong direction rejected. This
+  creates intentional distinction without forcing novelty into product UI.
+
+Respect the existing identity (default, ~90%); depart only on an explicit signal.
+
+## 4. Scope: task-scoped, never persisted
+Name the output target so sketch-vs-ship isn't guessed: **fidelity** (sketch / mid-fi /
+high-fi / production. DevRites default is production), **breadth** (one screen / a flow /
+a surface), **interactivity**, **time intent**. These ride in the brief only; they do not
+change the project's design system, and never get written to `PRODUCT.md` / `DESIGN.md`.
+
+## 5. Key states + interaction model
+List every state the feature needs and what the user must see/feel in each (default,
+loading initial+subsequent, empty→next-action, error→recovery, success, disabled/
+no-permission, long-content/overflow), the information hierarchy (what's seen 1st / 2nd /
+3rd; primary action unmistakable), responsive reflow, a11y must-haves, and the interaction
+model (inline vs navigated vs (rarely) modal; optimistic vs pending; feedback). Name the
+representative states, viewports, input modes, and target R-ids that will prove the result;
+"looks polished" is not a proof target. Canonical state list:
+`../devrites-frontend-craft/reference/shape.md`.
+
+## 6. Visual-direction probe: capability-gated
+When the work is net-new or directionally ambiguous and fidelity ≥ mid-fi, pressure-test
+the lane with something concrete instead of words: pull Figma context, generate image
+probes, screenshot reference sites, or route a code-fidelity question to `/rite-prototype`.
+**Capability-gated**: announce the skip in one line if no tool is available. Flow:
+[reference/visual-direction-probe.md](reference/visual-direction-probe.md).
+
+## 7. AI-slop pre-check
+Run the two-altitude category-reflex check (`../rite-polish/reference/anti-ai-slop.md`) on
+the chosen direction *before* writing the brief, if the palette/theme is guessable from
+the category, rework the scene sentence and color strategy. Cheaper to catch the slop in
+the brief than in the build.
+
+## 8. Write the brief + gate
+Write `design-brief.md` ([reference/brief-template.md](reference/brief-template.md)):
+**compact** (3-5 bullets) when discovery was crisp, **full** when the surface is ambiguous
+or multi-screen. Don't pad a clear brief to look thorough; don't skip the pause to look
+fast. Then honor the run mode (`../devrites-lib/reference/standards/afk-hitl.md`):
+- **HITL:** present the brief and **STOP for explicit confirmation**. The pause is the
+  point: shape ends at the user's "go", not at your own certainty. Disagreement → revisit
+  the relevant discovery question.
+- **AFK:** assert the best-guess direction, record it in `decisions.md` + an advisory
+  `questions.md` entry, and proceed. A direction touching the irreversible-risk list still
+  pauses.
+
+Completion: the smallest useful brief exists; primary action, states, interaction, proof
+targets, and reference role/usage are explicit; the run-mode gate is resolved. Only then may
+UI code start.
+
+## Output
+```
+UX/UI shaped: <slug>
+Direction: <color strategy> · density <airy|balanced|dense>/motion <minimal|standard|expressive> · "<scene sentence>" · anchors: <ref A, ref B>
+States: <n listed>   Probe: <figma | images | prototype | skipped — no tool>
+Brief: design-brief.md (<compact | full>)
+Gate: <confirmed | awaiting confirmation | AFK-asserted>
+Next: /rite-define (UI slices map to the brief's states) — or /rite-build refines it per slice
+```
+
+## NEVER (ux-shape)
+- Never write code, markup, or a component here: produce the thinking, not the UI.
+- Never finalize the brief without naming the **primary action** and the **full state set**
+  (not just the happy path).
+- Never decide visual direction by taste when the project has a system: discover first.
+- Never treat an **inspiration** reference as a fidelity target: honor its recorded role.
+- Never skip the HITL confirmation pause "because the brief is obviously right": ask once,
+  wait.
+- Never re-derive the brief from scratch in `/rite-build`: refine the existing one.