Skip to content

docs(skills): add the minimal-code decision ladder to /feature Phase 0 #4008

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PierreBrisorgueil merged 2 commits into from
Jul 31, 2026
+18 −0
Merged

docs(skills): add the minimal-code decision ladder to /feature Phase 0 #4008

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5575cfa
docs(skills): add the minimal-code decision ladder to /feature Phase 0
PierreBrisorgueil Jul 31, 2026
adc0972
docs(skills): tighten the ladder rung-0 exit and the persisted-state …
PierreBrisorgueil Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .claude/skills/feature/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,11 +117,29 @@ For each user-facing flow this feature creates or modifies, identify:
- Works WITHOUT organizations enabled?
- No hard dependency on external services for core flow?

### 4b. Minimal-code ladder (run before presenting)

Challenge every **mechanism** this change would introduce — a schema field, a flag, a collection, an abstraction, a scheduled job. Stop at the first rung that holds:

0. **Does a product decision remove it?** — accept the cost, accept the failure, do nothing, or surface it to the user. This rung holds **only if the mechanism then disappears**; if the product still needs it, keep going down the ladder.
1. **Already in this codebase?** — reuse the helper, service or pattern.
2. **In the standard library?** — use it.
3. **A native platform feature?** (DB constraint/index, framework built-in) — use it.
4. **An already-installed dependency?** — use it.
5. **One line, a constant, or config?** — make it that.
6. Only then: build it, minimal.

**Persisted state is the expensive rung.** A schema field, collection or flag encoding a *policy* (a known-bad marker, a cap, a memo of a past failure) is not a code choice — code is deleted, data is migrated. Rung 0 is mandatory for it, and it needs an **explicit, blocking user confirmation in §5** before it is built — a yes on that specific state, never implied by the general plan validation.

**Never traded away** (lazy ≠ negligent): understanding the problem before picking a rung, validation at trust boundaries, error handling that prevents data loss, security, and anything the user explicitly asked for.

### 5. Present plan & ask questions

**STOP and present to the user:**
- Flows identified (happy + error + edge cases)
- Users impacted + notification plan
- **Ladder outcome (§4b)** — the **selected rung** first (`<rung> — <what it resolves to>`, e.g. `1 reuse — existing users service`), then one line per rejected mechanism (`<mechanism> — simpler option <X> rejected because <reason>`). A change that adds a mechanism and rejects nothing means nobody looked.
- **Persisted state, if any** — name it and **wait for an explicit yes on it**; a general "plan validated" does not cover it, and it is not built without that yes.
- Open questions or scope decisions

**Wait for user validation before coding.** (Non-interactive runs: Phase 0.0
Expand Down