@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/5w2h-analysis.md

@@ -0,0 +1,260 @@
+# 5W2H Analysis
+
+Reference guideline for Wing-1 deep-thinking work — the 5W2H systematic
+questioning method (What · Why · Who · When · Where · How · How-much) for
+comprehensive understanding of any topic, problem, or plan. Adopted under
+the **Reference-Guideline Sunset Policy** (see frontmatter `upstream` /
+`refresh_trigger` keys) and cross-referenced from:
+
+- [`deep-reading-analyst`](../../skills/deep-reading-analyst/SKILL.md)
+  — L1 Quick analysis depth.
+- [`refine-ticket`](../../skills/refine-ticket/SKILL.md)
+  — completeness check on a Jira / Linear ticket before estimation.
+- [`bug-investigate`](../../../src/domains/engineering-base/bug/investigate/command.md)
+  — gap analysis on an incident report before forming a hypothesis.
+
+> **Core principle:** "Quality of decisions equals quality of questions
+> asked." — 5W2H captures essence in seven dimensions.
+
+## When to Use
+
+Ideal for:
+
+- 📋 Quickly understanding complete article information
+- 🔍 Discovering information gaps and omissions
+- 📊 Evaluating plan feasibility
+- 💼 Analyzing business cases and proposals
+- 📝 Organizing complex information
+- ✅ Verifying information completeness
+
+Do **not** use when the user wants depth on a single dimension (use
+[`mental-models`](mental-models.md)) or pre-mortem on failure paths
+(use [`inversion-thinking`](inversion-thinking.md)).
+
+## The 7 Questions in Detail
+
+### W1: What (Content)
+
+**Core questions:**
+
+1. What is the main topic?
+2. What are the key claims / conclusions?
+3. What solutions are proposed?
+4. What core concepts are involved?
+5. What are the expected outcomes?
+
+**Deep inquiry:** What is the real problem? What is missing? What
+could go wrong? What are the alternatives?
+
+### W2: Why (Reasons)
+
+**Core questions:**
+
+1. Why discuss this topic now?
+2. Why is this solution effective?
+3. Why not choose other approaches?
+4. Why should the audience care?
+5. Why this timing?
+
+**Five Whys technique** — ask "why" five times to reach root cause:
+
+```
+Problem: [Surface issue]
+→ Why 1: [First layer]
+  → Why 2: [Second layer]
+    → Why 3: [Third layer]
+      → Why 4: [Fourth layer]
+        → Why 5: [Root cause] ← Real issue
+```
+
+### W3: Who (People)
+
+**Core questions:**
+
+1. Who is the target audience?
+2. Who are the stakeholders?
+3. Who is responsible for execution?
+4. Who benefits? Who loses?
+5. Whose expertise / cases are cited?
+6. Who is the author? (potential biases?)
+
+**Deep analysis:** stakeholder mapping · decision-makers vs. executors
+· who has veto power.
+
+### W4: When (Timing)
+
+**Core questions:**
+
+1. When to start?
+2. What is the timeline / schedule?
+3. When will results appear?
+4. How time-sensitive is this?
+5. When are key decisions needed?
+6. What is the historical context?
+
+**Time-trap identification:** unrealistic time expectations · missing
+key milestones · buffer time considered.
+
+### W5: Where (Context)
+
+**Core questions:**
+
+1. Where does this apply? (geography, industry, organization)
+2. Where is execution happening?
+3. Where to get resources?
+4. What are the limitations / constraints?
+5. What is the scope of impact?
+
+**Context dependency:** does it work in different environments? ·
+cultural differences · scale considerations.
+
+### H1: How (Methods)
+
+**Core questions:**
+
+1. What are the specific steps?
+2. What tools / methods are used?
+3. How to measure progress?
+4. How to handle obstacles?
+5. How to ensure quality?
+6. How to get started?
+
+**Process mapping:**
+
+```
+[Start] → [Step 1] → [Decision Point]
+                         ↓ Yes / ↓ No
+                    [Step 2A]  [Step 2B]
+                         ↓         ↓
+                    [Step 3] ← [Converge]
+                         ↓
+                    [End]
+```
+
+### H2: How Much (Metrics)
+
+**Core questions:**
+
+1. What is the cost? (money, time, opportunity, learning)
+2. How many resources needed?
+3. What is the expected ROI?
+4. What is the scale / magnitude?
+5. How big are the risks?
+6. What are the target metrics?
+
+**ROI analysis:**
+
+```
+Investment:
+- Direct costs:   [$]
+- Indirect costs: [$]
+- Total:          [$]
+
+Returns:
+- Expected benefit: [$]
+- Timeframe:        [X months]
+- ROI = (Benefit - Cost) / Cost × 100%
+
+Worth it?: [Yes / No]
+```
+
+## Complete Analysis Template
+
+### Quick version (15 min)
+
+```markdown
+# 5W2H Quick Analysis: [Article Title]
+
+**What**:     [One-line topic and solution]
+**Why**:      [Core motivation and value]
+**Who**:      [Target audience and executors]
+**When**:     [Timeline and urgency]
+**Where**:    [Applicability and context]
+**How**:      [Key steps (3–5)]
+**How much**: [Main costs and expected returns]
+
+## Gap Analysis
+
+Missing information: [List unanswered questions from 5W2H]
+Key risks:           [Risks based on missing info]
+```
+
+### Deep version (60 min)
+
+```markdown
+# 5W2H Deep Analysis: [Article Title]
+
+## 📋 What — Content Analysis
+[Detailed breakdown…]
+
+## 🎯 Why — Reason Analysis
+[Detailed breakdown…]
+[Five Whys analysis]
+
+## 👥 Who — People Analysis
+[Detailed breakdown…]
+[Stakeholder map]
+
+## ⏰ When — Time Analysis
+[Detailed breakdown…]
+[Timeline visualization]
+
+## 🌍 Where — Context Analysis
+[Detailed breakdown…]
+[Applicability matrix]
+
+## 🔧 How — Method Analysis
+[Detailed breakdown…]
+[Process flowchart]
+
+## 💰 How Much — Cost-Benefit Analysis
+[Detailed breakdown…]
+[ROI calculation]
+
+## 📊 Overall Assessment
+
+### Information completeness
+- ✅ Clearly answered:   [X / 7]
+- ⚠️  Partially answered: [List]
+- ❌ Completely missing: [List]
+
+### Feasibility score
+Based on 5W2H completeness: [X / 10]
+
+### Risk level
+Based on missing info: [High / Medium / Low]
+
+### Action recommendations
+1. [Specific recommendation based on analysis]
+2. [Information needed to supplement]
+3. [Priority actions to take]
+```
+
+## Integration with Other Frameworks
+
+### + Critical Thinking
+
+```
+5W2H              → Identify missing information
+Critical Thinking → Evaluate quality of existing information
+```
+
+### + SCQA
+
+```
+SCQA  → Understand problem framework
+5W2H  → Analyze solution completeness
+```
+
+### + Inversion
+
+```
+5W2H      → Forward analysis of plan
+Inversion → For each W / H, ask "what if it's missing?"
+```
+
+---
+
+## ADOPT citation
+
+Adapted from an external reference.

package/dist/agent-src/guidelines/agent-infra/active-remediation-mechanics.md

@@ -0,0 +1,99 @@
+# Active Remediation — Mechanics
+
+> Ladder detail, version-gated modernization, and anti-nagging guardrails for the `active-remediation` rule
+
+_Origin: migrated from `src/rules/active-remediation.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law, the ladder tier names, and the live-security carve-out stay in the rule; this file carries the per-tier criteria and the modernization gates._
+
+## The ladder — classify, then act
+
+### Fix now (autonomous, inline) — a bounded amendment to `minimal-safe-diff`
+
+Allowed **only** when ALL hold — this is the testable "small + task-aligned" definition:
+
+- **Same request path / module** as the current task (not an unrelated feature).
+- **≤ ~10 changed lines** in one production file plus its test file — no wider cross-file ripple.
+- **No public-API / response-shape change**, no new parameter.
+- **No dependency bump, no migration, no data change.**
+- **Its verification ships in the same commit** — e.g. the security fix's negative test, or the correctness fix's case.
+
+Under those constraints the fix is auditable in the same diff and is *not* scope creep — it corrects a boundary the agent touched. Anything outside them → the fix is **note + ask**, never auto. (`minimal-safe-diff` still governs everything else: no reformatting, no opportunistic refactor, no drive-by rename.)
+
+### Note + ask (batched)
+
+Bigger, or diverges from the task → do **not** refactor inline, do **not** interrupt the flow. Note the site (file:line + the issue). Surface the batch as **one** numbered-options prompt (per `user-interaction`, one recommendation line) **after the task is delivered** — or mid-work only when the flow makes it natural. Each option must carry a real trade-off (`no-cheap-questions`). Refactor only on an explicit yes, as a separate scoped change (`scope-control`, `downstream-changes`).
+
+#### Option anatomy — a pickable fix, not a yes/no
+
+The user should be able to answer with one number and get a change they can predict. Each numbered option therefore names four things, in a line or two:
+
+1. **What changes** — the concrete edit, in the vocabulary of the code ("replace the three `array()` literals with `[]`", not "clean up the file").
+2. **Where** — file, or the group of files if the option covers a batch.
+3. **How large** — line count or an honest size class, so the user can weigh it without opening the diff.
+4. **What it costs** — the risk, the review burden, or the reason it was not simply done inline.
+
+Group findings by **fix shape**, never one option per finding: seven lint errors that are three `no-unused-vars`, three `prefer-const` and one genuine type hole are three options, not seven. The final option is always an explicit **leave it as is** — its absence is what turns a menu into pressure. One recommendation line under the block names your pick (`user-interaction` Iron Law 1).
+
+#### Carry-over — undecided is not finished
+
+An item the user has not answered stays live: raise it once more at the next natural task boundary, in the same batched form. Two bounds keep that from becoming nagging:
+
+- **A decline is terminal.** An explicit "leave it" / "ignore" closes the item for the task; re-raising it is the re-ask `scope-control` § Decline = silence forbids.
+- **Once per boundary, not once per reply.** The batch is a task-close artifact. Repeating it between steps is the continuation prompt `no-cheap-questions` Iron Law 4 forbids.
+
+### Propose a follow-up PR (many spots)
+
+When the issues are too many to fold in without blowing the current diff's scope, propose **one or more separate follow-up PRs** (or a roadmap under `agents/roadmaps/`, using the shared-prefix convention) so the user reviews the changes before merge. Creating the PR/roadmap is **permission-gated** — propose, get a yes, then create (`scope-control`, `commit-policy`).
+
+## Observed failing checks — classifying the red you already have
+
+The rule puts a check result you have already seen into the same ladder as a defect you read in a file. Running a command, reading seven errors, and walking past them is not scoping the work — it is looking away.
+
+The rule's two bounds, in full:
+
+- **Only output you already have.** The clause never obliges a check run; it fires on a result already in front of you. What runs locally stays the user's call — this package records "no proactive quality tools, remote CI gates only" as a standing preference — and the remote CI remains the authoritative gate. An obligation to *hunt* for red would contradict that outright; an obligation not to walk past red you already read does not.
+- **Ownership picks the tier, never the silence.** Caused by your diff → it is the task. Pre-existing and inside the fix-now bar → fix it. Pre-existing and wider, or many, or unrelated → note + ask, or a follow-up PR. There is no seventh option called "mention it in the closing summary" — that line reads as a status report and closes nothing.
+
+Classification is the whole of the work, and it runs on two axes:
+
+| | Inside the fix-now bar | Outside it |
+|---|---|---|
+| **Caused by this diff** | Fix it — it is the task, not remediation. | Fix it; a diff you cannot make green is not deliverable. Blocked → surface it as a blocker, never as a caveat. |
+| **Pre-existing** | Fix it with the work, and say in the commit body that it was pre-existing. | Note + ask with candidate fixes, or a follow-up PR when the batch is large. |
+
+Two failure shapes this table exists to name:
+
+- **"Not mine, so not mentioned."** Pre-existing red is the most common thing an agent walks past, because `minimal-safe-diff` reads like permission to ignore it. It is not: that rule bounds the *diff*, this one bounds the *silence*. The two are satisfied together by noting the finding and asking, which changes no line of code.
+- **"Mine, so quietly worked around."** A gate that goes green because the check was narrowed, an assertion loosened, or a file excluded is a defect with a green light on top. Route it through the ladder as an issue, and say what was narrowed.
+
+### Worked example — a red gate seen mid-task
+
+> the `check` task fails; the lint step reports 7 errors, all pre-existing on `main`, in files this branch does not touch.
+
+Wrong, and the canonical shape of it: finish the task, and close with *"the only thing still open is the lint finding — 7 errors on main, which makes the `check` task unusable as a chain"*. The sentence is accurate, the issue is named, and nothing about it is decided — the next session inherits it verbatim.
+
+Right: the errors are pre-existing, outside the fix-now bar (unrelated files, more than ~10 lines), so they are **note + ask** — after the task is delivered, one block:
+
+1. Fix the 3 `no-unused-vars` in `src/a.ts`, `src/b.ts` — ~6 lines, mechanical, ships in this PR.
+2. Fix all 7 in a separate follow-up PR — keeps this diff single-purpose; needs a branch (permission-gated).
+3. Suppress the two in generated output with a scoped ignore, fix the rest — smallest green path, adds a suppression to review.
+4. Leave as is — the `check` task stays unusable as a chain until someone else picks it up.
+
+One recommendation line names the pick. Whatever the user answers, the item is closed. If they answer nothing, it is raised once at the next task boundary — not carried silently into a third session.
+
+## Version-gated modernization
+
+Update stale idioms to the version the project **actually runs** — but only when that version is **verified**:
+
+- **Establish the version first** from the manifest constraint (`composer.json` `require`, `package.json` `engines`, `.tool-versions`, lockfile) — use the **lowest** bound; on an ambiguous/monorepo range, ask once. **Unknown version → do not touch** (must fit the project structure — this is the `source-discovery` gate).
+- **Syntax-only, behavior-preserving idioms** (e.g. `array()` → `[]`, `isset($x)?$x:$d` → `$x ?? $d`, string concat → template) that are provably equivalent → treat as a small fix (auto per the ladder).
+- **Behavioral changes** (`readonly`/typed properties, new language semantics) and **any dependency/version bump** → **ask only**, never auto (a version bump stays under `minimal-safe-diff`'s no-dependency-bump prohibition; a pure syntax idiom is categorically different).
+
+## Guardrails — don't become a nagging machine
+
+- Subordinate to `no-cheap-questions` (self-check items 3 & 14 — real trade-off, not a disguised continuation/commit ask), `autonomous-execution` (the end-of-session batch must not read as "shall I continue?"), `user-interaction`, `ask-when-uncertain` (one batched prompt = one question).
+- Threshold to surface at all: a **real, nameable** improvement with a concrete benefit. Cosmetic nitpicks with no trade-off → drop silently. The live-security carve-out is the only case that interrupts or overrides autonomy.
+
+## See also
+
+- [`active-remediation`](../../rules/active-remediation.md) — the rule this file details (Iron Law + ladder + live-security carve-out).
+- [`minimal-safe-diff`](minimal-safe-diff-mechanics.md) — the diff-shape mechanics the fix-now tier amends.

package/dist/agent-src/guidelines/agent-infra/agent-interaction-and-decision-quality.md

@@ -0,0 +1,325 @@
+# agent-interaction-and-decision-quality
+
+Improves how the agent asks questions, handles uncertainty, learns from feedback,
+and integrates quality rules into CI.
+
+## Core principles
+
+- Do not guess when clarification is cheap
+- Do not overwhelm the user with too many complex questions at once
+- Prefer structured decision-making over assumptions
+- Learn from negative feedback and turn it into system improvements
+- Integrate recurring improvements into rules, skills, or CI
+
+## 1. Question strategy
+
+### Simple decisions
+
+If questions are simple binary or small choices — ask multiple at once, numbered clearly:
+
+```
+1. Use Tailwind or existing styles?
+2. Add tests? (yes/no)
+3. Extend existing component or create new one?
+```
+
+### Complex questions
+
+If questions require thinking, context-create, or explanation:
+
+- Ask ONE question at a time
+- Wait for answer before continuing
+- Do not bundle multiple complex topics together
+
+### Handoff / model-switch questions
+
+If a handoff (e.g. model change, deeper analysis) is required:
+
+1. First ask all necessary domain questions (step-by-step if complex)
+2. Then ask the handoff question LAST
+
+Reason: answers must be available before switching context — avoids incomplete downstream instructions.
+
+## 2. No blind implementation
+
+Before implementing, analyze what already exists:
+
+- Identify used frameworks, libraries, patterns
+- If multiple UI systems exist (e.g. Tailwind, shadcn, custom): ask which one to use
+- Do NOT pick one arbitrarily or start implementation without alignment
+
+## 3. Handling unclear requirements
+
+If instructions are incomplete:
+
+- Do NOT assume missing behavior
+- Do NOT silently decide critical aspects
+- Ask precise clarification questions or output a structured clarification request
+
+## 4. Learning from negative feedback
+
+If the user complains, says something is wrong, or shows frustration:
+
+1. Do NOT ignore or defend blindly
+2. Extract the underlying failure pattern
+3. Convert it into one of:
+   - Rule (constraint to prevent recurrence)
+   - Skill improvement (better workflow step)
+   - Guideline addition (reference convention)
+   - Linter check (if recurring and automatable)
+
+> Every mistake should improve the system.
+
+## 5. CI integration mindset
+
+When introducing new quality patterns, consider whether they should be enforced automatically.
+
+If unsure, ask:
+- "Should this be enforced via CI?"
+- "Should this be part of the linter?"
+
+Prefer consistent enforcement over manual discipline.
+
+## 6. Decision transparency
+
+When making decisions:
+
+- State what you assumed
+- State what alternatives exist
+- State why a decision was made
+- If the decision is important: confirm with the user before proceeding
+
+## 7. Efficiency in interaction
+
+- Avoid long back-and-forth caused by poor initial questions
+- Avoid rework caused by wrong assumptions
+- Prefer: short clarification early → correct implementation once
+
+## 8. Improve before implement — pre-implementation validation
+
+_Origin: migrated from `src/rules/improve-before-implement.md` per the P4 pattern of `road-to-kernel-and-router.md`. The rule keeps the activation lists and the golden rule ("Challenge to improve, never to refuse"); the check detail lives here._
+
+Before coding a new feature, refactor, module, or behavior-altering change, quickly verify:
+
+### 8-pre. Demand gate — should this exist at all? (build / defer)
+
+One altitude ABOVE engineering-fit. Fires on a "build me an app / add this
+feature" ask, before checks 8a–8c. It is a three-question advisor, NOT a
+product-management framework — surface it in one short block, then proceed on
+the user's answer (never block; `improve-before-implement`'s golden rule holds).
+
+**Read the addressee before the questions.** The ladder below measures **market
+demand**, and market demand is a meaningful quantity only where a market is
+intended. Who the project is built for is `project.audience` — resolve it with
+`agent-config settings:get project.audience`, which reports the value and the
+file it came from, rather than opening one file. An absent value resolves to
+`public`, and mechanically so: the template-defaults layer supplies the shipped
+value beneath every file layer (`src/scripts/_lib/agent_settings.ts:873`) and
+`project.audience` is not in the `settingsCarveOut` set, so absent and an
+explicit `public` are the same behaviour. (It used to explain the
+same conclusion with "this package has no defaults layer" — true of the retired
+`_DEFAULTS`, false since that layer shipped. The conclusion never moved; the
+reason did, and the reason decides how far a change to the shipped
+default would reach.)
+
+| `project.audience` | What 8-pre does |
+|---|---|
+| `self` | **Inert.** One line — "demand gate skipped (audience: self)" — then straight to 8a. No deferral, no demand question. |
+| `internal` | Question 2 only ("what breaks without it?"). Questions 1 and 3 are already answered — the requester is the team. |
+| `client` | The requester is the client, not a segment. Question 2 survives; 1 and 3 are answered by the engagement. |
+| `public` | **Today's behaviour, unchanged** — all three questions and the full ladder. |
+
+Three questions:
+
+1. **Who requested this?** (a real user / segment, or an internal hunch?)
+2. **What happens if you DON'T build it?** (churn / blocked deal, or nothing measurable?)
+3. **What's the demand evidence?** (requests, usage data, lost revenue — or a feeling?)
+
+Map the answers to a compressed feature-demand hierarchy and recommend:
+
+| Level | Signal | Recommendation |
+|---|---|---|
+| L-self | The maintainer needs it for their own work — no user population is intended | **Build** |
+| L0 | Founder/agent anxiety — "it feels missing" | **Defer** — validate demand first |
+| L1 | One anecdotal request, no pattern | **Defer** — watch for repetition |
+| L2 | Repeated requests, no measured impact | **Validate** — instrument before building |
+| L3 | Blocks activation/retention for a real segment | **Build** |
+| L4 | Users are churning / deals lost without it | **Build now** |
+
+Build at **L-self**, **L3**, or **L4**; L0–L2 get a defer/validate
+recommendation with the one missing evidence named.
+
+`L-self` is not a weaker L3. L3 and L4 are defined exclusively over third-party
+users — "a real segment", "users are churning" — so a project with no intended
+user population cannot reach either, not because it is bad but because the scale
+has no value for it. Its ceiling on the L0–L4 ladder is L0, whose recommendation
+is *defer*, which would defer a single-user tool forever. `L-self` is the level
+that ladder is missing, not a discount on the ones it has.
+
+**The artefact consequence.** At `L-self`, or at `audience: self` / `internal`,
+never write a roadmap gate, exit criterion, or opening condition that names an
+external user population, a market, or an external measurement. A gate whose
+condition depends on a quantity the project cannot produce is not a gate — it is
+a permanent no in the shape of an answer. This is where the advisory reading
+actually breaks: in conversation "never block" holds, but when a roadmap needs a
+falsifiable opening condition the agent reaches for the only vocabulary it has
+for *should this exist*, and an advisory ladder becomes a number, then a gate.
+
+This is advisory — the user decides; a "just build it" answer proceeds
+immediately to 8a. No network, no case-memory API (the source's remote lookup is
+dropped — a lethal-trifecta egress concern).
+
+**Enforcement, honestly.** Nothing reads `project.audience` to change what this
+section does. § 8-pre is prose and the branch table above is model-carried —
+the same honesty boundary `security-sensitive-stop` and `untrusted-input-defense`
+state for their own obligations. The one deterministic backstop sits downstream,
+where the damage actually lands: `lint_roadmap_complexity` warns when a roadmap
+gate rests on an external population.
+
+### 8a. Is the request clear?
+
+- Are acceptance criteria defined or derivable?
+- Is the scope bounded? (not "make it better" but "add X to Y")
+- Are edge cases considered?
+
+**If unclear** → ask ONE focused question per turn (`ask-when-uncertain` Iron Law — serial, never batched), never an interrogation.
+
+### 8b. Does it fit the existing architecture?
+
+- Does similar functionality already exist?
+- Does it follow established patterns in the codebase?
+- Does it contradict existing conventions?
+- Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`strategy.md`](../php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+
+**If misfit** → show evidence (file references), propose alternative.
+**If multiple valid options** → list them, ask which to use. See [§ 2 — No blind implementation](#2-no-blind-implementation).
+
+#### 8b-ladder. The solution-size ladder — stop at the first rung that works
+
+"Does similar functionality already exist?" is one question with an **ordered**
+answer set. Walk it top-down and stop at the first rung that carries the
+requirement; each rung down costs more code to write, own, and eventually
+delete. Ordered **after** comprehension, never instead of it — the ladder
+shortens the solution, never the reading.
+
+| # | Rung | The question |
+|---|---|---|
+| 1 | **Need to exist** | Does this have to be built at all? (§ 8-pre decides) |
+| 2 | **Reuse in repo** | Does a unit already in this codebase do it? |
+| 3 | **Stdlib / framework** | Does the language stdlib or the framework already do it? |
+| 4 | **Native platform** | Does the OS, runtime, browser, or database already do it? |
+| 5 | **Installed dependency** | Is it already in the dependency tree? |
+| 6 | **Smallest working form** | Of what genuinely must be written, what is the least of it? |
+
+Rungs 1, 2, 3, 5 and 6 are obligations this suite already states elsewhere
+(§ 8-pre; § 8b above and [`component-oriented-and-oop-development`](../component-oriented-and-oop-development.md)
+"Reuse before you build"; `architecture`'s "use the framework's primitive";
+[`supply-chain-intake`](../../skills/supply-chain-intake/SKILL.md) step 0;
+`minimal-safe-diff`'s smallest-change Iron Law) — the ladder **orders** them, it
+does not add them.
+
+**Rung 4 is the one that was missing.** Between "the framework does it" and "add
+a dependency" sits the platform the code already runs on: `crypto.randomUUID`
+before a uuid package, a database's own JSON / full-text / generated-column
+support before an application-side index, `AbortSignal.timeout` before a timeout
+helper, `Intl` before a formatting library, a filesystem watcher before a polling
+loop. A dependency added for something the platform already ships is permanent
+cost bought against a capability you already had.
+
+#### 8b-shape. The shape axis — simple is not the same as short
+
+The ladder above is the **scope** axis: must this exist, and can something
+cheaper serve? The **shape** axis is the other half: of what must exist, which
+form carries the **least cognitive load** — explicitly *not* the fewest
+keystrokes.
+
+A flat version one line longer beats a dense clever one. A one-liner qualifies
+as the "smallest working form" only when it is also the *simplest* form, not
+merely the shortest — nested ternaries, long optional-call chains, and clever
+one-expression reductions all shrink the diff while raising the cost of every
+future read. The failure mode is measured, not theoretical: generated code
+trends shorter but denser, carrying more cognitive load per line. A size metric
+on its own rewards exactly that.
+
+Read with [`code-clarity`](../code-clarity.md), which owns the line-level form
+decisions and states the same distinction from the other direction.
+
+#### 8b-precedence. Resolution order when these pull against each other
+
+Stated once, here, so the clauses above never issue contradictory simultaneous
+instructions. Higher wins:
+
+1. **Safety floors** — `engineering-safety-floor`, `security-sensitive-stop`,
+   and `senior-engineering-discipline`'s invisible cross-cutting controls. A
+   rung that saves a line by dropping a guard has lost, not won.
+2. **Explicit user-fenced scope** — "just this one line" ends the ladder.
+3. **Shape** (simplicity) — a simpler form beats a smaller one.
+4. **Scope** (don't build it) — a cheaper rung beats a lower rung.
+5. **De-duplication** — last, and gated: extract only when the repetition
+   trigger in [`minimal-safe-diff-mechanics`](minimal-safe-diff-mechanics.md)
+   § Anti-over-engineering fires, never as a reflex.
+
+Any pair is resolvable from this list alone. This is a **principle** ordering
+and deliberately *not* an entry in `docs/contracts/rule-interactions.yml`, which
+is a pairwise contract scoped to the always-on kernel rules — forking that
+linted contract with a second prose ordering over a different kind of object is
+the drift this ladder exists to avoid.
+
+
+### 8c. Is the approach sound?
+
+- Is there a simpler way to achieve the same result?
+- Are there known problems with the requested approach?
+- Does the scope match the stated goal? (not over-engineered, not under-specified)
+
+**If problematic** → explain the concern, propose a better approach.
+
+### How to challenge
+
+- **Be concise** — one sentence per concern, not paragraphs
+- **Show evidence** — reference existing code, patterns, or conventions
+- **Offer alternatives** — don't just say "this is wrong"
+- **Use numbered options** — let the user choose quickly
+- **Respect "just do it"** — if the user insists after your challenge, execute immediately
+
+Example:
+
+```
+> ⚠️ `UserService` already has a `deactivate()` method that covers this case.
+>
+> 1. Use existing method — extend with new parameter
+> 2. Create new method anyway — I'll explain the overlap in a comment
+> 3. Skip validation — implement as requested
+```
+
+After presenting concerns: user picks an option → execute immediately; user says "just do it" → execute immediately. Never argue twice about the same point. Never block work — delay is only justified if it prevents a clear mistake.
+
+### Scope limits
+
+- **Max 1-2 challenges per task** — not every request needs validation
+- **Max 1 minute of analysis** — if the check takes longer, skip it
+- **Never validate simple tasks** — only features, architecture, significant changes
+- **Never validate after the user already explained their reasoning**
+
+### Verify with concrete tools, not prose
+
+If the challenge requires you to confirm current behavior before proposing an alternative, use a concrete probe — a `curl` against the endpoint, a Playwright spec, a debugger / `xdebug` step-through, or the project's test runner with a targeted filter. Asserting current behavior from memory is not validation.
+
+### Intent inference (RDP, standard host)
+
+When the literal request and the underlying goal may differ, **state the inferred goal in one line and give ONE recommendation** — do not spread 2–3 framings (that is the overplanning [`direct-answers`](../../rules/direct-answers.md) suppresses). Standard host only; a strong-reasoning host self-infers, so skip it there. Engage per [`rdp-gate`](../../contexts/execution/rdp-gate.md).
+
+## Anti-patterns
+
+- Asking 5 complex questions at once
+- Mixing clarification and implementation in the same step
+- Doing handoff before collecting required context
+- Blindly choosing frameworks/tools without checking existing usage
+- Ignoring user frustration instead of learning from it
+- Introducing new quality rules without considering CI enforcement
+- Making important decisions silently without stating reasoning
+
+## Final principle
+
+> Ask better → decide better → build once → improve system continuously