Add simplicity ladder recipe and review criterion

AGENTS.md

@@ -58,6 +58,7 @@ _shared/
   recipes/
     phase-override-resolution.md  # Project-level phase override lookup and activation
     self-review-gate.md           # Pre-PR self-review quality gate (used by bugfix, implement, e2e, cve-fix)
+    simplicity-ladder.md          # Simplest-viable-implementation decision checklist (used by bugfix, implement)
 ```
 
 Recipes are self-contained, parameterized procedures that workflows reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from `skills/`).
@@ -135,7 +136,8 @@ ai-workflows/
 │   ├── sizing-rubric.md       # Shared sizing definitions and heuristics
 │   └── recipes/
 │       ├── phase-override-resolution.md  # Project-level phase override lookup
-│       └── self-review-gate.md  # Pre-PR self-review quality gate
+│       ├── self-review-gate.md  # Pre-PR self-review quality gate
+│       └── simplicity-ladder.md  # Simplicity decision ladder
 ├── ai-ready/                  # Workflows (auto-discovered via SKILL.md)
 ├── bugfix/
 ├── code-review/

_shared/recipes/simplicity-ladder.md

@@ -0,0 +1,52 @@
+---
+name: simplicity-ladder
+version: 0.1.0
+---
+# Recipe: Simplicity Ladder
+
+A quick decision checklist for choosing the simplest viable implementation.
+Referenced by code-producing workflows before writing new code.
+
+## The Ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist?** If the requirement is already met by
+   existing code, or the feature is speculative — stop. YAGNI.
+2. **Stdlib does it?** Use the language's standard library. Don't wrap it.
+3. **Native platform feature?** Use it — OS API, runtime built-in,
+   framework primitive, HTML/CSS over JS.
+4. **Already-installed dependency?** Check existing deps before adding new
+   ones. Never add a dependency for what a few lines can do.
+5. **One-liner?** If the solution fits in one clear line or expression,
+   write the one-liner. Don't build infrastructure around it.
+6. **Minimum code that works.** Write the smallest correct implementation.
+   No speculative abstractions, no premature generalization.
+
+The ladder is a reflex, not a research project. Two rungs work — take the
+higher one and move on.
+
+## When NOT to Simplify
+
+Do not simplify past correctness in these areas:
+
+- **Trust boundaries** — input validation, authentication, authorization
+- **Data-loss paths** — persistence, backup, transaction handling
+- **Security** — cryptography, secret management, access control
+- **Accessibility** — a11y requirements are not optional complexity
+- **Explicitly requested features** — if the story or ticket asks for it,
+  build it
+
+## The `ceiling:` Comment Convention
+
+When the ladder leads to a simpler approach that has a known limit,
+optionally leave a `ceiling:` comment at the decision point:
+
+```text
+// ceiling: >5 routes with middleware → consider a router
+```
+
+The ceiling names the condition under which the simple choice stops
+being adequate. It tells future maintainers when to revisit, not how
+to refactor. Only add one when the limit is non-obvious — most simple
+choices don't need annotation.

_shared/review-protocol.md

@@ -1,6 +1,6 @@
 ---
 name: review-protocol
-version: 0.1.0
+version: 0.2.0
 ---
 # Code Review Protocol
 
@@ -55,14 +55,21 @@ Evaluate changes against these categories, prioritized by impact:
    (missing intermediate type), a type importing from several unrelated
    packages (mixed concerns), identical error-handling blocks repeated
    across call sites (missing shared helper), a new interface that exposes
-   internal types to callers.
-5. **Performance** — Are there unnecessary allocations, N+1 queries, unbounded
+   internal types to callers. (For stdlib/platform/dependency preference,
+   see Simplicity.)
+5. **Simplicity** — Does the code use stdlib or platform features where they
+   suffice? Are there unnecessary dependencies or hand-rolled implementations
+   of things the standard library already provides? Could the code be shorter
+   without losing clarity? Signals: a new dependency for something the standard
+   library handles, a wrapper that only delegates, verbose code where a
+   one-liner would be equally clear.
+6. **Performance** — Are there unnecessary allocations, N+1 queries, unbounded
    operations, or other efficiency concerns?
-6. **Naming and clarity** — Are names descriptive? Is the intent clear from
+7. **Naming and clarity** — Are names descriptive? Is the intent clear from
    reading the code?
-7. **Test coverage** — Are the changes tested? Are edge cases covered? Are
+8. **Test coverage** — Are the changes tested? Are edge cases covered? Are
    tests testing contracts, not implementation?
-8. **Project conventions** — Do the changes follow the conventions discovered
+9. **Project conventions** — Do the changes follow the conventions discovered
    from the project's AGENTS.md, CLAUDE.md, linting configs, and contribution
    guidelines?
 

bugfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bugfix
-version: 0.2.0
+version: 0.3.0
 description: >-
   Diagnostic and repair workflow that analyzes error logs, traces root causes,
   implements fixes, and verifies with regression tests.

bugfix/guidelines.md

@@ -25,6 +25,7 @@ Artifacts go in `.artifacts/bugfix/{issue}`.
 - When you're wrong, admit it quickly and course-correct.
 - Don't assume tools are missing. Check for version managers (e.g. `uv`, `pyenv`, `nvm`) before concluding a runtime isn't available.
 - **Be thorough and complete**: When fixing bugs involving states, phases, or conditions, search the codebase to identify the complete set of possible values. Don't assume you know all variants. When features interact (e.g., polling + pagination), research and understand their interactions before implementing.
+- **Prefer the simplest viable fix.** Before writing new code, run through the simplicity ladder (`../_shared/recipes/simplicity-ladder.md`). Use stdlib, platform features, and existing dependencies before adding new code or new dependencies. A minimal fix that uses what's already available is safer than one that introduces new abstractions.
 
 ## Hard Limits
 

bugfix/skills/fix.md

@@ -36,6 +36,7 @@ Implement targeted bug fixes that resolve the underlying issue without introduci
 ### Step 3: Implement Core Fix
 
 - Write the minimal code necessary to fix the bug
+- Apply the simplicity ladder (`../../_shared/recipes/simplicity-ladder.md`): prefer stdlib, platform features, and existing deps over new code or new dependencies
 - Follow project coding standards and conventions
 - Add appropriate error handling and validation
 - Include inline comments explaining **why** the fix works, not just **what** it does

code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-version: 0.2.0
+version: 0.2.1
 description: >-
   AI-driven code review workflow that reviews uncommitted changes using a
   discoverable reviewer profile, presents findings for human decision, and

code-review/skills/start.md

@@ -266,8 +266,8 @@ Write `.artifacts/code-review/{branch}/code-review-001.md`:
 - **File:** {file path}
 - **Location:** {line range or function name, as applicable}
 - **Severity:** {CRITICAL | HIGH | MEDIUM | LOW}
-- **Category:** {Correctness | Error Handling | Security | Performance |
-  Naming/Clarity | Test Coverage | Conventions}
+- **Category:** {Correctness | Error Handling | Security | Design |
+  Simplicity | Performance | Naming/Clarity | Test Coverage | Conventions}
 - **Issue:** {what the problem is}
 - **Suggestion:** {concrete, actionable fix}
 

cve-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cve-fix
-version: 0.2.0
+version: 0.2.1
 description: >-
   Automated CVE remediation that reads vulnerability details from a Jira ticket,
   applies multi-strategy dependency fixes, validates results, and creates pull

e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e
-version: 0.2.0
+version: 0.2.1
 description: >-
   Story-to-e2e-test workflow that takes a Jira [QE] Story, discovers the
   project's e2e testing infrastructure, plans test scenarios, writes e2e

implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: implement
-version: 0.2.0
+version: 0.3.0
 description: >-
   Story-to-code workflow that takes a Jira Story, plans the implementation,
   writes contract-based tests and production code via TDD, validates against

implement/guidelines.md

@@ -6,6 +6,7 @@
 - **Tests validate contracts, not implementations.** Test through public interfaces. Every behavioral path reachable through a public interface is a distinct contract that needs its own test case. Tests should remain valid if the implementation were rewritten.
 - **Unit tests are always required. Integration tests are required when the story touches component interactions** (API-to-service, service-to-store, agent-to-server). Unit and integration tests are complementary, not alternatives.
 - Follow the **project's existing patterns.** Read neighboring code and tests before writing new code. Match naming conventions, package organization, test style, and error handling patterns.
+- **Prefer the simplest viable implementation.** Before writing new code, run through the simplicity ladder (`../_shared/recipes/simplicity-ladder.md`). Use stdlib, platform features, and existing dependencies before adding new code or new dependencies.
 - **Follow the project's commit format** as discovered during `/ingest` and recorded in the validation profile. Commit one logical unit of work per commit — typically one commit per plan task. Don't batch everything into a single commit, but don't create a commit per file either.
 - Each completed story must leave the system in a **stable state**. All tests pass, linter is clean, no regressions.
 - The implementation plan is a **living document**. Update `02-plan.md` as tasks are completed so it reflects current progress.

implement/skills/code.md

@@ -184,10 +184,11 @@ Write the production code that makes the tests from 3b pass:
 
 1. Follow existing code patterns in the package
 2. Match naming conventions, error handling style, and documentation patterns
-3. If the task involves modifying generated code (e.g., OpenAPI specs),
+3. Apply the simplicity ladder (`../../_shared/recipes/simplicity-ladder.md`): prefer stdlib, platform features, and existing deps over new code
+4. If the task involves modifying generated code (e.g., OpenAPI specs),
    modify the source specification and run the generation command
-4. Keep changes focused on what the task describes
-5. Code comments describe what the code does and why — not the process
+5. Keep changes focused on what the task describes
+6. Code comments describe what the code does and why — not the process
    of arriving there. Do not reference abandoned approaches or prior
    states that no longer exist
 

implement/skills/plan.md

@@ -44,6 +44,7 @@ Before writing the plan, create a mental map:
 - Which changes have dependencies on each other (ordering constraints)?
 - Where will tests live? What test patterns from neighboring code should be followed?
 - Are integration tests needed? (Yes, if the story touches component interactions like API-to-service, service-to-store, agent-to-server.)
+- Does any proposed new type, interface, or function duplicate what stdlib, the platform, or an already-installed dependency provides? Apply the simplicity ladder (`../../_shared/recipes/simplicity-ladder.md`) to each planned component.
 
 ### Step 3: Write the Implementation Plan