devrites 5.10.2 → 5.12.0

package/pack/generated/devin/skills/devrites-lib/reference/standards/developer-experience.md

@@ -0,0 +1,121 @@
+# Developer experience
+
+> Applies when: shipping a surface another engineer uses: API, CLI, SDK, config.
+
+When a change ships a surface another engineer has to *use* (a public API, a CLI, an SDK
+or library, a webhook, a config/env contract, an error message, or the getting-started path
+that introduces all of them) the developer using it is a user, and their experience is part
+of the change. Code that compiles and passes its tests can still strand the next developer at
+a cryptic error, a getting-started snippet that doesn't run, or an endpoint whose shape you
+have to read the source to learn. Un-tested DX is a claim, the same way un-run code is a claim.
+
+This rule is the developer-facing counterpart to [`performance.md`](performance.md): perf says
+*measure the speed before you assert it*; this says *measure the experience before you assert
+it*. It pairs with the [`devrites-api-interface`](../../../devrites-api-interface/SKILL.md)
+skill (which shapes the contract). This rule **proves** the shape is usable.
+
+## Scope: when this applies
+
+Conditional, like [`performance.md`](performance.md) and [`observability.md`](observability.md).
+It applies when the diff changes a **developer-facing surface**:
+
+- a public/external **API** endpoint, response shape, or status-code contract;
+- a **CLI** command, flag, output, or exit code;
+- an **SDK / library / package** export, signature, or type;
+- a **webhook**, event payload, or integration contract;
+- a **config / env-var** interface a consumer must set;
+- an **error message, exit code, or failure response** a developer reads to recover;
+- the **getting-started path**. README, install steps, quickstart, the first-run docs.
+
+Skip it for pure-internal refactors, private helpers, app-only UI (that's
+[`devrites-frontend-craft`](../../../devrites-frontend-craft/SKILL.md) /
+`devrites-frontend-reviewer`), docs-only typo fixes, and config that no external consumer
+touches. Don't DX-review a change with no developer-facing surface: the same scope discipline
+as the rest of the conditional rules. End-user UX is a different axis; this rule is about the
+*developer* consuming the surface.
+
+## The boomerang: predict at plan, measure at prove, reconcile at seal
+
+DevRites already runs a predict-then-prove spine (the vetted `test-plan.md` coverage target at
+`/rite-vet`, proven at `/rite-prove`, gated at `/rite-seal`). DX rides the same spine, and the
+gap between the two ends is the signal:
+
+1. **Predict:** at `/rite-vet`, when a developer-facing surface is in scope, score the *planned*
+   surface against the dimensions below and write a predicted scorecard to `devex.md` (the
+   estimate, e.g. "time-to-hello-world: ~3 min"). This is cheap and pre-build; it forces the
+   ergonomics question before the contract sets.
+2. **Measure:** at `/rite-prove`, exercise the surface (run the getting-started flow,
+   call the endpoint, invoke the CLI, trigger the error) and record the *measured* scorecard with
+   evidence: real TTHW, security-redacted exact error text, and a safely captured docs screenshot.
+3. **Reconcile (the boomerang):** at `/rite-seal`, compare predicted against measured. A material
+   gap: "the plan said 3 minutes, the getting-started flow took 8 and step 4 errored":
+   is a finding, not a rounding error. The estimate was wrong *or* the surface regressed; either
+   way the developer using it pays, and the gap is exactly what a single end-state score would hide.
+
+The boomerang is what makes DX a measured axis rather than an opinion: the prediction is on
+record, so the measured reality can falsify it.
+
+## The scorecard: what to score
+
+One entity, one name: call the metric **time-to-hello-world (TTHW)** consistently, not "onboarding
+time" in one place and "setup time" in another. Score these dimensions; only the ones the diff
+touches:
+
+- **Discoverability:** can a developer find the entry point without reading the source? Is the
+  new surface named, exported, and documented where they'll look?
+- **Time-to-hello-world (TTHW):** wall-clock from "I have the repo/package" to "I got one
+  successful call/response/render". The headline number; measure it, don't estimate it at seal.
+- **Getting-started friction:** does the quickstart run *as written*, copy-pasted, on a clean
+  checkout? Every undocumented prerequisite, wrong command, or missing step is friction.
+- **Error-message quality:** does a failure say *what* failed, *why*, and *how to recover*, with
+  the relevant ids (never secrets: see [`security.md`](security.md))? A bare stack trace, a
+  silent exit, or "an error occurred" is a defect on a developer-facing path.
+- **Ergonomics & consistency:** does the surface match the project's existing conventions
+  (naming, argument order, pagination, error shape)? An inconsistent new endpoint taxes everyone
+  who learned the old ones. Sensible defaults; the common case is one call.
+- **Docs accuracy:** examples are copy-pasteable and correct, the signature in the docs matches
+  the code, and changed behavior updated its docs in the same change ([`documentation.md`](documentation.md)).
+
+## Measure, don't assert
+
+The same discipline as `performance.md` "measure first" and `testing.md` "see it fail first":
+
+- **Run it, don't read it.** A scorecard backed by "the code looks fine" is Source mode and says
+  so. The graded scorecard comes from invoking the surface (the getting-started flow on
+  a clean state, the real CLI `--help`, the real error path) and recording what happened.
+- **Quote the artifact.** Record exact signal-bearing error text with typed security redactions
+  (not paraphrase), secret-free command shape, and measured TTHW. For docs, use the
+  [browser-proof ladder](../../../devrites-browser-proof/SKILL.md) and describe the screenshot;
+  a path alone is not proof.
+- **No measurement → no DX claim**, and usually no finding above Suggestion. "Feels confusing" is
+  a hypothesis to test, not a verdict.
+
+## The gate: severity by who-pays
+
+DX findings carry the standard labels (Critical / Important / Suggestion / Nit / FYI), scaled to
+the cost the consumer bears, not to how polished it feels:
+
+- A **public/external contract that ships broken or wrong** (a documented command that errors, an
+  endpoint whose response contradicts its contract, a getting-started flow that can't complete) is
+  **Important**, and **Critical** when it's a frozen public surface (the principles-gated public-API
+  invariant, [`principles.md`](principles.md)) or an irreversible break.
+- A **measured DX regression** against the predicted scorecard with no recorded reason is a
+  finding the boomerang surfaces at seal, at least **Important** when it lands on a public surface.
+- An **unactionable error message** on a developer-facing failure path is **Important**: the
+  on-call test ([`observability.md`](observability.md)) applied to the consumer instead of the operator.
+- Inconsistent-but-working ergonomics, a thin doc, a missable default → **Suggestion**, unless the
+  spec made it acceptance.
+
+## The artifact: `devex.md`
+
+When a developer-facing surface is in scope, the workspace carries `devex.md`: the **predicted**
+scorecard (from `/rite-vet`), the **measured** scorecard with evidence (from `/rite-prove`), and
+the **boomerang delta** (reconciled at `/rite-seal`). Absent surface → no `devex.md`, and the gate
+passes silently: never block a change for the *absence* of a DX surface, the same no-op discipline
+as the principles and spec-grammar gates.
+
+## Scope discipline
+
+Review the developer-facing surface the change *touches*. A surface the diff didn't change is not
+this change's job; a project-wide DX audit (every endpoint, the whole CLI) is its own effort:
+record it as a follow-up, don't smuggle it into an unrelated change.

package/pack/generated/devin/skills/devrites-lib/reference/standards/development-workflow.md

@@ -0,0 +1,31 @@
+# Development workflow
+
+> Applies when: slicing work, committing, keeping trunk green.
+
+Ship small, integrate often, and keep the main branch releasable. Workflow phase order comes from the engine manifest, not this standard.
+
+## Work in small batches
+- Break work into thin, independently shippable slices and integrate them frequently:
+  ideally merging to the main branch at least once a day.
+
+## Short-lived branches, trunk always green
+- Prefer short-lived branches off the main branch.
+- The main branch is **always in a releasable state**. Validate every change through a
+  **fast, reliable CI pipeline** (tests + build) before it merges.
+- **Trunk broken?** Revert first (default repair); fix forward only when revert is harder. Red trunk blocks all merges.
+- Hide incomplete work behind a **feature flag / toggle** rather than a long branch, so
+  partial work can land without blocking releases or breaking the trunk.
+
+## Feature-flag lifecycle
+
+- Name the **removal trigger** at flag creation; delete the flag once the work ships — a
+  flag past its trigger is **flag debt**, a review finding. Prove **both states**
+  ([`testing.md`](testing.md)); widen rollout only with the rollback path recorded
+  ([`data-integrity.md`](data-integrity.md)).
+
+## Review gate
+- A human reviews every change before merge; `code-review.md` owns review scope and evidence.
+
+## Definition of done
+
+[`definition-of-done.md`](definition-of-done.md) owns the standing bar. Acceptance criteria prove the slice-specific behavior; the Definition of Done proves the change is shippable.

package/pack/generated/devin/skills/devrites-lib/reference/standards/documentation.md

@@ -0,0 +1,55 @@
+# Documentation
+
+> Applies when: writing docs, comments, READMEs; recording decisions.
+
+Document intent/decisions; public inputs, outputs, errors, and gotchas; non-obvious
+constraints; and real build/test/run commands. Update with behavior; prefer one runnable
+example. Do not restate code or types.
+
+## Drift check (docs describe what runs)
+
+A documented command/example that no longer runs is a **documentation-drift finding** at
+review/polish: run it — failure plus output is the evidence. A behavior change updates the
+doc or records the divergence; doc and code never hold contradictory "truths".
+
+## Record decisions
+
+- Capture significant context, decision, consequences, accepted trade-off, change trigger,
+  and why viable alternatives lost. DevRites uses `decisions.md` for feature decisions.
+- ADRs move `PROPOSED → ACCEPTED → SUPERSEDED / DEPRECATED`. Preserve accepted history;
+  a replacement ADR cites and supersedes the old one rather than rewriting it.
+
+## Promote durable guidance
+
+Promotion is maintenance of an existing authority, not a new memory system.
+
+1. **Trigger:** the same reviewed correction appears in at least two distinct features, or
+   one explicit product/architecture decision has durable rationale. A one-off, generic,
+   stale, or merely inferred observation does not trigger promotion.
+2. **Ground:** verify each current claim against live authoritative repository sources.
+   Report the source and currentness signal. Unverifiable means `unknown`, not false.
+3. **Scope:** state when the guidance applies and does not apply. Reject a candidate whose
+   observable trigger cannot be named. If final code/tests/docs already recover the
+   reasoning, reject or consolidate the lesson; promote only the missing durable constraint.
+   **Failing case:** a regression test already explains input rejection, yet a second
+   generic "validate input" rule is added with no lost reasoning identified.
+4. **Own and expose:** choose one existing canonical owner (`AGENTS.md`/`CLAUDE.md`, a scoped
+   standard, or an ADR) and name the phases, agents, or contributors that discover it and
+   how (direct read, index link, or existing on-demand route).
+5. **Reconcile:** search current guidance for duplicates, contradictions, and supersession.
+   Update, narrow, replace, or retire contradicted guidance at its owner; do not append a
+   competing rule. Record the conflict/retirement disposition.
+6. **Approve:** show evidence and the exact durable edit before writing; user approval is
+   required. Never create a learning ledger, index, queue, score, or parallel authority.
+
+Long reference material stays behind its existing on-demand route.
+
+## Living documents
+
+Canonical documents are updated, not appended to. When truth changes, rewrite the
+owning section in the present tense; sealed artifacts take dated deltas through the
+owning rite instead ([`core.md`](core.md) #4). Pick a steering verb deliberately —
+`create`, `consolidate`, `split`, `trim`, `retire` — rather than letting the last-opened
+file absorb every new topic. Document what code cannot own (contracts, invariants,
+decisions, rationale); a doc that restates implementation drifts the day it lands.
+Sparse is correct — never pad a document to look complete.

package/pack/generated/devin/skills/devrites-lib/reference/standards/duplicate-code.md

@@ -0,0 +1,118 @@
+# Duplicate code
+
+> Applies when: a review or polish pass needs near-duplicate leads that survive
+> renaming, or a dup finding needs a dismissal that persists.
+
+`devrites-engine check dup` is the deterministic scanner. It normalizes source
+(strips comments, collapses strings, canonicalizes identifiers and literals),
+matches token shingles between files, clusters overlapping matches, and prints
+advisory clusters — **leads**, not findings. The engine never judges whether a
+cluster is worth merging; that decision is semantic and belongs to the
+reviewer. Successful scans exit 0 even with clusters; usage and operational
+errors, including incomplete scans, exit 2.
+
+## Running it
+
+```text
+devrites-engine check dup [slug] --worktree|--staged|--base <ref>|--all
+    [--min-lines n] [--threshold f] [--ignore-file <path>]
+    [--limit n] [--exclude <csv>]
+```
+
+- `--staged` / `--worktree` / `--base <ref>`: scan the repo, then print only
+  clusters with a unit overlapping the diff's changed hunks, marked `*`. Pick
+  the mode matching the diff under review: `--base <ref>` when the feature's
+  commits are landed (the common `/rite-review` case), `--staged`/`--worktree`
+  for uncommitted diffs. `--staged` reads index blobs for every comparator and
+  excludes untracked files, regardless of working-tree edits or deletions.
+  Keep the index stable during the scan. Other modes read working-tree bytes.
+- `--all`: whole-repo triage, includes untracked source files. Use in
+  `/rite-polish` or `/devrites-audit` passes.
+- `--min-lines` (default 8): minimum meaningful overlap. Lower it for tiny
+  helper-heavy languages, raise it to cut boilerplate noise.
+- `--threshold` (default 0.6): minimum similarity score per reported pair.
+- `--exclude`: extra path prefixes to skip (fixtures, generated code).
+- `dup: scanned … units` in the header is the coverage line — a scan of 3
+  files in a 300-file repo proves nothing.
+
+## Evidence limits
+
+This is a bounded heuristic, not exhaustive duplicate detection. The scanner
+limits eligible files (8,192), source bytes (64 MiB total, 1 MiB per file),
+Git listing/diff output (16 MiB), repeated-shingle postings, pair anchors, and
+reported clusters. Normalization loses language semantics; a successful scan
+with no leads does not prove the repository has no duplication.
+
+No eligible input and intentional generated exclusions are reported explicitly
+with exit 0, without claiming a successful source scan. Unreadable/non-regular
+source, unresolved index entries, Git failures, and input resource limits exit 2.
+A partial scan may print available leads, but never an `ok` verdict or a success
+metric. Generated exclusions are counted separately from unavailable input.
+Repeated options, conflicting modes, missing/flag-like values, and nonfinite
+thresholds fail before scanning or metrics. Diff helpers and text conversion
+are disabled so configured executables cannot change the inspected evidence.
+
+## Output shape
+
+```text
+dup: scanned 42 files (2 skipped), 17 units; ignore-file .devrites/dup-ignore
+dup: 2 cluster(s) (1 ignored)
+cluster 1 (a1b2c3d4e5f6) score 0.93:
+  * engine/a.go:10-58
+    engine/b.go:120-168
+cluster 2 (f6e5d4c3b2a1) score 0.81:
+    pkg/x/util.py:30-70
+    pkg/y/util.py:14-54
+```
+
+`*` marks a unit that overlaps the diff's changed lines. The hex after
+`cluster N` is the cluster's stable hash.
+
+## Triage each cluster
+
+For every reported cluster a reviewer returns exactly one verdict:
+
+| Verdict | When | Action |
+|---|---|---|
+| **merge** | Same logic, same contract, no behavioral reason to differ | Finding: extract a shared helper or call the canonical implementation. Name which unit survives. |
+| **keep** | Convergent code (test scaffolding, protocol mirrors, intentional fork points) | Record the cluster hash in the ignore ledger with a one-line reason. |
+| **watch** | Similar now, likely to diverge — copied seed that is about to change | FYI finding noting the drift risk; do not ignore. |
+
+Ranking boosts distant matches across directories or far apart within one file.
+Distance is a triage hint, not proof that two contracts are interchangeable.
+Check whether fixes to one copy should also apply to the other.
+
+## Ignore ledger
+
+`.devrites/dup-ignore` (project-root default; `--ignore-file` overrides) holds
+one cluster hash per line, `#` comments allowed:
+
+```text
+a1b2c3d4e5f6  # test scaffolding mirrors on purpose — do not merge
+```
+
+The hash derives from normalized code *content*, not line numbers. It survives
+renames, comment churn, literal tweaks, and line moves, but **changes when the
+code's structure changes** — a dismissed cluster that gets edited resurfaces
+for re-triage. This is intentional: a ledger entry must never permanently
+blind the scan.
+
+Rules:
+
+- Never add a hash without reading both units — an unread dismissal is a gap.
+- Write the reason on the same line after `#`; a bare hash is an unexplained
+  dismissal and counts as a skipped check.
+- Do not commit-ignore clusters introduced by the *current* diff — a `*` unit
+  needs a verdict (merge/keep/watch), not suppression.
+
+## Reporting dup findings
+
+Dup findings use the C2 shape like any other finding, plus the cluster hash so
+the dismissal ledger can reference it:
+
+```text
+Finding: Suggestion | engine/a.go:10 | cluster a1b2c3d4e5f6 duplicates engine/b.go:120 (score 0.93) | fixes to one will drift from the other | extract shared helper `dupNormalize` into engine/internal/lib
+```
+
+A reviewer that ran `check dup` and found nothing reports it under
+`No-findings:` / `Basis:` (`dup: 0 clusters over 42 files`) — not by silence.

package/pack/generated/devin/skills/devrites-lib/reference/standards/edge-case-trace.md

@@ -0,0 +1,94 @@
+# Edge-case trace
+
+> Applies when: a boundary, branch, or failure mode changes in spec, plan, diff, or proof.
+
+Use this when requirements, plans, diffs, or proof change a boundary, branch,
+validation rule, deletion contract, retryable action, or claim that a path is safe.
+The trace finds relevant cases, records why irrelevant ones were dismissed, and prevents
+confidence from turning an untested negative claim into a pass.
+
+## Scope before enumeration
+
+Name the observable surface, caller/actor, state or data it owns, external boundaries,
+and the must-NOT outcome the author would reject even if the happy path worked. Do not
+expand into a whole-system checklist: a class applies only when the changed surface can
+reach it.
+
+## Closed probe classes
+
+Probe each relevant class once:
+
+| Class | Questions |
+| --- | --- |
+| Boundary | Empty/missing, minimum/maximum, off-by-one, oversized, invalid encoding/shape. |
+| State | Initial, repeated, stale, terminal, illegal transition, interruption and resume. |
+| Ordering | Duplicate, out-of-order, retry, partial completion, clock/time-zone boundary. |
+| Concurrency | Competing writer, lost update, cancellation, race, deadlock or resource exhaustion. |
+| Authority | Unauthenticated, unauthorized, wrong tenant, forged identity, privilege increase. |
+| Dependency | Timeout, partial/invalid response, rate limit, outage, version/config mismatch. |
+| Persistence | Transaction split, crash, migration/backfill restart, rollback, retention/deletion. |
+| Compatibility | Old/new reader or writer, caller not updated, feature-flag off/on, environment difference. |
+| Wiring | Code exists but is not registered, called, awaited, persisted, emitted, or consumed with real data. |
+| Removal | Deleted behavior, caller, data, telemetry, docs, or fallback has no surviving owner. |
+
+Route detailed applicable cases to
+[`repository-topology.md`](repository-topology.md),
+[`data-integrity.md`](data-integrity.md),
+[`integration-reliability.md`](integration-reliability.md), or
+[`security.md`](security.md); do not repeat those standards here.
+
+## Trace procedure
+
+1. **Walk explicit paths.** Follow every changed condition, loop exit, error, and
+   boundary value to the nearest observable outcome.
+2. **Walk fixed-set siblings.** A special case for one enum/status/role/mode implies
+   every untouched sibling is a path to check.
+3. **Follow real wiring.** Verify existence, substance, registration/call path, and
+   real data flow. A complete-looking implementation can still be hollow, orphaned,
+   or a stub.
+4. **Check negative intent.** Ask what silently permitted outcome would violate a
+   requirement, invariant, non-goal, or security boundary. Add a prohibition only
+   when bespoke intent is not already owned by a standard.
+5. **Check removal.** Name the contract removed code carried and its surviving owner,
+   or cite the accepted decision that retires it.
+
+## Disposition and evidence
+
+Every applicable case receives one status:
+
+- `covered`: mapped to a REQ/AC and positive discriminating test or observed runtime proof;
+- `backstop`: an independent held-out, property/metamorphic, or direct behavioral check
+  names the wrong outcome it would detect — and is **exogenous**: not produced or
+  executed by the same code path it validates (a check the changed code also controls is
+  `covered` evidence, not a backstop);
+- `dismissed`: unreachable or irrelevant with a concrete reason and supporting evidence;
+- `unresolved`: a material case lacks a fact or proof surface and blocks the owning gate.
+
+Judgment may dismiss a demonstrably irrelevant case; it cannot prove behavior. When a
+case is not inferable from available evidence, say `unresolved`/`cannot_verify` rather
+than estimating confidence upward.
+
+## Backstop honesty (fail-closed)
+
+A row marked `covered` or `backstop` **must** name an evidence class: test path,
+command output, observed runtime, or an independent held-out/property check. A row
+with disposition but **no** evidence class is **`cannot_verify`** at Prove/Seal — not
+a pass.
+
+**Failing case:** the happy-path suite is green, the trace lists "error path handled"
+with no test or runtime proof → Prove blocks until the row gains a discriminating
+surface or moves to `unresolved`.
+
+## Outputs
+
+Spec records relevant cases in **Edge Coverage** and bespoke negative intent in
+**Prohibitions**. Plan/Vet maps applicable cases to a slice, recovery, and proof. Review
+reports only reachable gaps:
+
+```md
+Finding: <severity> | path:line | <trigger> reaches <unhandled outcome> | <observable harm> |
+<minimal handling>; missing proof: <test/signal>.
+```
+
+Use the caller's severity scale. Do not create a separate edge score, pad rows with
+irrelevant classes, or report a case already handled and proven.

package/pack/generated/devin/skills/devrites-lib/reference/standards/elicitation.md

@@ -0,0 +1,114 @@
+# Elicitation: a move-set for the thinking phases
+
+> Applies when: a thinking phase needs more than the default review shape for a section.
+
+The thinking phases (`/rite-temper` on the spec, `/rite-vet` on the plan) default to one shape each.
+A pre-mortem, a plan review. That's a floor, not a ceiling. When a section needs deeper thought,
+this is the menu you reach into: named reasoning techniques, each with the shape it produces, so
+"make this stronger" becomes a concrete move instead of a vibe.
+
+## How to use it (progressive: no ceremony by default)
+1. Look at the **one section** in front of you (a requirement, a risk, an estimate, a boundary).
+2. Read its **risk**, then pull the 3-5 techniques below whose *When to reach for it* matches.
+3. Present them as a short numbered menu; the human picks one (or `skip`).
+4. Run that technique on that section, apply the result, move on.
+5. **No-yield exit:** when the technique surfaces nothing that changes the section — no
+   new requirement, mitigation, estimate change, or blocking question — record
+   `elicitation: <technique> — no yield` in the phase artifact and stop offering menus
+   for that section. **Failing case:** repeated technique menus on a settled section are
+   ceremony, not diligence; a second menu without new section input is a process defect.
+
+Selection is by the section's risk, not taste. Reach for the row that fits:
+
+| The section is… | Reach for |
+|---|---|
+| an irreversible / boundary / auth / data-model decision | Red-Team vs Blue-Team · Assumption Audit · Pre-Mortem |
+| a vague or contested requirement | Steelman-then-Attack · Devil's Advocate · Five Whys |
+| an estimate, sizing, or a "how long / how risky" | Delphi · Reference-Class Forecast |
+| a design with more than one plausible shape | Tournament (A vs B) · Inversion · Analogy Mapping |
+| a plan or patch that may be solving the wrong problem | Backward Chain |
+| a spec that feels *too* big or *too* small | Scope Extremes (MVP vs Gold-plate) · YAGNI Pass |
+| a risk surface you suspect is under-explored | Chaos Scenarios · Edge-Case Hunt · Second-Order Effects |
+
+## The techniques
+
+Each entry is **name (when to reach for it) the shape it produces** (`→` reads "then").
+
+### Sharpening a claim
+- **Steelman-then-Attack:** a requirement or approach you're inclined to accept. Build the
+  *strongest* case for it → then attack that strongest form. Survives → keep; falls → revise.
+- **Devil's Advocate:** consensus formed too fast. One voice argues the opposite in good faith →
+  surface the objection the room skipped.
+- **Assumption Audit:** a plan resting on unstated beliefs. List every assumption the section
+  makes → mark each *load-bearing / verified / unverified* → the unverified load-bearing ones are
+  the work.
+- **Five Whys:** a stated requirement whose *reason* is fuzzy. Ask "why" five times down from the
+  ask → reach the root need (often narrower or different than the surface ask).
+
+### Stress-testing a decision
+- **Pre-Mortem:** before committing an irreversible choice. Assume it's six months later and this
+  failed → write the failure story → each cause becomes a mitigation or a blocking question. (This
+  is `/rite-temper`'s default; the others deepen it.)
+- **Red-Team vs Blue-Team:** a security, trust-boundary, or adversarial-input surface.
+  `defense → attack → hardening`: state the defense, attack it as a hostile party, harden the gap.
+- **Inversion:** "how do we make X good?" stalls. Ask instead "how would we *guarantee X fails*?"
+  → invert each failure into a requirement.
+- **Second-Order Effects:** a change that touches shared surface. For each first-order effect ask
+  "and then what?" twice → surface the downstream consequence the diff hides.
+- **Backward Chain:** a plan or patch that may be solving the wrong problem. Write the desired end
+  state as one checkable sentence → ask "what must be true immediately before it?" → recurse to the
+  current state → any planned step that does not land on the chain is wrong-direction work; name the
+  tempting one explicitly.
+
+### Sizing and estimating
+- **Delphi:** an estimate one person is anchoring. Gather independent estimates *without* seeing
+  each other → reveal → discuss the spread → re-estimate → converge. Kills anchoring.
+- **Reference-Class Forecast:** "this'll be quick." Find 3 past changes of the same *class* → use
+  their actual cost as the base rate, not the inside view.
+
+### Widening the option space
+- **Tournament (A vs B):** two plausible designs. Put them head-to-head on the *decision hinge*
+  (the one axis that differs) → pick on that axis, not on a feature checklist.
+- **Analogy Mapping:** a novel problem. "What is this *like* that's already solved?" → borrow the
+  solved structure, note where the analogy breaks.
+- **Scope Extremes:** a spec of uncertain size. Describe the *MVP* (smallest thing that ships
+  value) and the *gold-plated* version → the right scope is usually named by the gap between them.
+- **YAGNI Pass:** a plan carrying "might need it later." For each speculative piece, demand a
+  *current* acceptance criterion → no criterion, cut it to a follow-up.
+
+### Finding what's missing
+- **Edge-Case Hunt:** a happy-path-shaped spec. Walk empty / boundary / invalid / concurrent /
+  huge-or-weird input for each element → each uncovered case is a missing criterion.
+- **Chaos Scenarios:** a system with external dependencies. "What if the DB is down / the API
+  times out / the clock jumps / the input is hostile?" → each becomes a failure-mode requirement.
+- **Completeness Critic:** end of a section. Ask only "what's *missing*: a modality not covered, a
+  claim not verified, a flow with no path?" → the answer is the next round of work.
+
+## The one rule
+Run the technique on the **section in front of you**, not the whole document: a move applied to
+everything is a move applied to nothing. Record what it changed in the phase artifact (a new
+requirement, a mitigation, a blocking question), not just that you ran it.
+
+## Asking mechanics
+
+- **Batch 2–4 independent questions;** ask serially when one answer determines the next
+  question or the question is an approval gate.
+- **Never ask for the discoverable** — repo, docs, prior artifacts, and conversation
+  first; a question whose answer sits in a file is a stall dressed as diligence.
+- **One decision per question** with enough context to answer without reopening files;
+  recommend a path and name its trade-off — never raw unevaluated options.
+- **At an approval gate, state the defaults you chose** so a wrong assumption gets
+  corrected before it ships.
+- **Never continue past a question by inventing the answer** — headless sessions report
+  the unresolved decision instead of assuming it.
+- **A skipped, declined, or timed-out answer is `unanswered`, not approval.** A
+  proposal, silence, or timeout never becomes a decision. Continue only work the
+  open decision cannot affect; when the unanswered question blocks scope,
+  spending, publication, or anything irreversible, stop and name the specific
+  unresolved choice — do not reissue the same question as if nonresponse were an
+  error.
+- **No question tool → numbered text fallback.** Two to four concrete options,
+  each with its trade-off, one marked as the recommendation, and a free-text
+  escape. A recommendation is labeled, never pre-selected.
+
+A project can append its own house techniques to this file: same entry shape — **name (when to reach for it)** → the shape it produces.

package/pack/generated/devin/skills/devrites-lib/reference/standards/error-handling.md

@@ -0,0 +1,49 @@
+# Error handling
+
+> Applies when: code can fail; error paths, messages, retries, partial state.
+
+Errors are part of the contract, not an afterthought. Make failure loud, local, and
+recoverable.
+
+## Fail fast
+- Validate preconditions at the top; stop the moment state is invalid, close to the root
+  cause. Don't let bad data propagate and surface as a confusing failure three layers
+  later.
+
+## No silent catches
+- Never swallow an error to make a problem "go away", that hides bugs and corrupts
+  state silently.
+- Catch the **narrowest** error you can handle, not a blanket catch-all. A
+  bare/broad catch masks unrelated failures.
+- If you catch, either recover meaningfully, or rethrow/wrap with added context. Don't
+  log-and-continue past an error you didn't handle.
+
+## Classify the outcome before retrying
+
+Never retry blind — match the outcome first:
+
+- **Rejected** (refused: validation/authz/conflict): fix input; unchanged retry fails again.
+- **Unknown** (timed out mid-call): check state at the source before any retry.
+- **Partial** (half-committed): [`data-integrity.md`](data-integrity.md) (see `Writes, retries, and concurrency`) — reconcile or roll back, never resume blind.
+- **Clean failure** (not started / fully rolled back): safe to retry after fixing the cause.
+
+**Failing case:** an **Unknown** outcome retried unchanged double-applies (duplicate charge). Idempotency: [`data-integrity.md`](data-integrity.md); outcome taxonomies: [`integration-reliability.md`](integration-reliability.md). Not provable → `cannot_verify` and stop.
+
+## Meaningful messages
+- Error messages state what failed, the relevant context (ids, inputs, not secrets),
+  and ideally how to recover. Cryptic messages cost hours.
+- Distinguish *expected* failures (validation, not-found) from *unexpected* (bugs);
+  handle the first as flow, surface the second.
+- Structured error surfaces carry one consistent envelope — **severity, stable code,
+  human message, fix** — so callers and logs can act programmatically; a bare string that
+  forces callers to parse prose is a contract gap.
+
+## Fail closed (security-relevant paths)
+- On error in an auth/permission/transaction path, **deny and roll back**: never
+  default to granting access or committing partial state.
+
+## Logging
+- Log key events (failures, access violations, validation errors) with enough context to
+  debug. Prefer structured logs (key/value or JSON).
+- **Never log secrets, credentials, tokens, or personal data.** Show users a clear,
+  non-revealing message; keep the detail in the logs for the team.