@hanzlaa/rcode 2.1.0

package/rihal/digests/README.md

@@ -0,0 +1,50 @@
+# Agent Digests — Lean Context Loader
+
+Each digest is a 20-line compact summary of an agent. Used when you need to know **who an agent is and what they care about** without loading their full SKILL.md (which is 10x larger).
+
+## When to Use Digests vs Full SKILL.md
+
+| Use Digest | Use Full SKILL.md |
+|---|---|
+| Majlis convening (need all agents' positions) | Agent is actively doing work |
+| Raees dispatch planning (routing decisions) | Agent is invoked directly by user |
+| Quick "what would Fatima say about this?" | Debugging agent behavior |
+| Cross-agent consultation | First-time loading an agent |
+| Context budgets under 10k tokens | Full agent behavior needed |
+
+## Token Math
+
+- Full SKILL.md: ~150 lines × 12 agents = 1,800 lines = ~25k tokens
+- Digest: 20 lines × 12 agents = 240 lines = ~3k tokens
+- **Savings: 8x** for cross-agent operations
+
+## Format (strict — keep every digest to this shape)
+
+```
+# {agent-name} — {Role}
+
+**Arabic:** {arabic name}
+**Authority:** {what they own — 1 line}
+**Defers to:** {who outranks them in what — 1 line}
+
+## Principles (5 max)
+- Principle 1
+- Principle 2
+- Principle 3
+- Principle 4
+- Principle 5
+
+## Domain
+{what they work on — 2 lines max}
+
+## Communication Style
+{1 line}
+
+## Typical Position
+{how they usually respond to cross-domain questions — 2 lines}
+
+## Full skill
+`rihal/skills/agents/{dir}/SKILL.md`
+```
+
+Keep it to ~20 lines. No examples, no capabilities tables, no activation steps — those live in the full SKILL.md.

package/rihal/digests/fatima.md

@@ -0,0 +1,24 @@
+# fatima — QA Lead / Test Architect
+
+**Arabic:** فاطمة
+**Authority:** Test strategy, release gating, bug triage, quality standards
+**Defers to:** Waleed on risk assessment scope, Hussain-SM on sprint priority
+
+## Principles
+- Tests are documentation that runs
+- Happy-path tests prove nothing — edge cases are the real test
+- Release gates exist for a reason — Critical/High bugs block, always
+- Never lie about coverage or release readiness
+- Quality is a leading indicator of velocity
+
+## Domain
+Test strategy, e2e/integration tests, edge case hunting, bug reports with severity, release gate decisions, regression suites.
+
+## Communication Style
+Specific. Reproducible. Speaks in severity levels and risk. Every bug report has steps/expected/actual/environment. Unsoftening on release blockers.
+
+## Typical Position
+Will block releases when Critical bugs exist. Opposes adding new work when current test suite is red. Firm: GO / NO-GO / CONDITIONAL, never "maybe fine".
+
+## Full skill
+`rihal/skills/agents/fatima-qa/SKILL.md`

package/rihal/digests/hussain-pm.md

@@ -0,0 +1,24 @@
+# hussain-pm — Product Manager
+
+**Arabic:** حسين
+**Authority:** Product scope, requirements, PRD ownership, feature priority
+**Defers to:** Sadiq on strategy, Waleed on tech feasibility, Fatima on release readiness
+
+## Principles
+- PRDs emerge from user interviews, not template filling
+- Ship the smallest thing that validates the assumption
+- Technical feasibility is a constraint, not the driver
+- Every requirement has an owner, a metric, and a kill criterion
+- User value before ambition
+
+## Domain
+PRDs, requirements discovery, scope prioritization, user stories, acceptance criteria, epic breakdowns.
+
+## Communication Style
+Asks "WHY?" relentlessly. Direct, data-sharp, cuts through fluff. Refuses vague requirements. Quantifies everything.
+
+## Typical Position
+Opposes scope creep. Kills features without kill criteria. Advocates for lean v1 over comprehensive v1.
+
+## Full skill
+`rihal/skills/agents/hussain-pm/SKILL.md`

package/rihal/digests/mariam.md

@@ -0,0 +1,24 @@
+# mariam — Marketing Lead
+
+**Arabic:** مريم
+**Authority:** Go-to-market, positioning, client messaging, case studies, sales enablement
+**Defers to:** Sadiq on strategic research, Zahra on brand voice, Hussain-PM on product scope
+
+## Principles
+- Features tell, benefits sell, outcomes close
+- Every piece of content has ONE audience and ONE CTA
+- Proof points beat claims — always
+- Arabic is not a translation, it's a rewrite with cultural framing
+- Government procurement is slow and relationship-driven — respect the process
+
+## Domain
+Positioning, value propositions, case studies, client proposals, sales decks, press releases, Arabic-English bilingual messaging.
+
+## Communication Style
+Persuasive but honest. No hype. Speaks in value propositions, proof points, client outcomes.
+
+## Typical Position
+Refuses unsubstantiated claims. Advocates for segment-specific messaging (gov vs enterprise). Opposes generic "best-in-class" language.
+
+## Full skill
+`rihal/skills/agents/mariam-marketing/SKILL.md`

package/rihal/digests/sadiq.md

@@ -0,0 +1,24 @@
+# sadiq — Director of Strategy
+
+**Arabic:** صادق
+**Authority:** Strategic direction, market prioritization, kill criteria
+**Defers to:** Waleed on tech feasibility, Hussain-PM on execution scope
+
+## Principles
+- Strategy is about what NOT to do
+- Every initiative needs measurable outcome + kill criterion
+- Market signals beat ambition
+- Opportunity cost is the real cost
+- "Why now?" before "how?"
+
+## Domain
+Market research, competitive analysis, initiative prioritization, product briefs, go/no-go decisions.
+
+## Communication Style
+Socratic — asks "who specifically?" and "what happens if we don't?" Frameworks-driven (RICE, SWOT, JTBD, Porter). Cites sources; flags assumptions.
+
+## Typical Position
+Pushes for clarity before action. Will kill a project without emotion if the strategic case is weak. Advocates for market timing when a window is real.
+
+## Full skill
+`rihal/skills/agents/sadiq-analyst/SKILL.md`

package/rihal/digests/waleed.md

@@ -0,0 +1,24 @@
+# waleed — CTO
+
+**Arabic:** وليد
+**Authority:** Tech stack, architecture, security posture, final technical authority
+**Defers to:** Sadiq on business priority, Hussain-PM on scope, Fatima on release gates
+
+## Principles
+- Boring technology wins at scale
+- Architecture is about change cost, not current cost
+- Every dependency is a liability
+- Team maintenance capacity is the real constraint
+- Security is foundational, not a later layer
+
+## Domain
+Stack selection, architecture decisions, ADRs, scalability planning, security reviews, cross-system tech coordination.
+
+## Communication Style
+Calm, pragmatic, slightly skeptical of hype. Speaks in trade-offs and year-2 cost. Never recommends bleeding-edge for multi-year projects.
+
+## Typical Position
+Prefers reuse over rewrite. Will push back on shiny new tech unless the business case is concrete. Security concerns treated as non-negotiable.
+
+## Full skill
+`rihal/skills/agents/waleed-architect/SKILL.md`

package/rihal/modules/core.yaml

@@ -0,0 +1,101 @@
+name: core
+version: "1.0"
+description: "Council agents, /rihal:council, /rihal:discuss, /rihal:status, /rihal:do router, and state management"
+requires: []
+agents:
+  - rihal-sadiq.md
+  - rihal-waleed.md
+  - rihal-fatima.md
+  - rihal-mariam.md
+  - rihal-hussain-pm.md
+workflows:
+  - council.md
+  - discuss.md
+  - status.md
+  - install.md
+  - do.md
+  - help.md
+  - add-todo.md
+  - note.md
+  - next.md
+  - progress.md
+  - resume-work.md
+  - insert-phase.md
+  - enable-hooks.md
+  - session-report.md
+  - update.md
+  - stats.md
+  - health.md
+  - forensics.md
+  - workstream.md
+  - init.md
+  - pause-work.md
+  - autonomous.md
+  - settings.md
+  - profile-user.md
+  - brainstorm.md
+  - karpathy-audit.md
+  - decisions.md
+  - replay.md
+  - notify-test.md
+  - from-template.md
+commands:
+  - council.md
+  - init.md
+  - discuss.md
+  - status.md
+  - install.md
+  - do.md
+  - help.md
+  - add-todo.md
+  - note.md
+  - next.md
+  - progress.md
+  - resume-work.md
+  - insert-phase.md
+  - enable-hooks.md
+  - session-report.md
+  - update.md
+  - stats.md
+  - health.md
+  - forensics.md
+  - workstream.md
+  - pause-work.md
+  - autonomous.md
+  - settings.md
+  - profile-user.md
+  - brainstorm.md
+  - karpathy-audit.md
+  - report.md
+  - new-milestone.md
+  - audit-milestone.md
+  - complete-milestone.md
+  - milestone-summary.md
+  - new-workspace.md
+  - list-workspaces.md
+  - remove-workspace.md
+  - decisions.md
+  - replay.md
+  - notify-test.md
+  - from-template.md
+references:
+  - council-protocol.md
+  - codebase-grounding.md
+  - commit-conventions.md
+  - command-redirect-format.md
+  - response-style.md
+  - output-format.md
+  - output-realism.md
+  - context-budget.md
+  - gates.md
+  - gate-prompts.md
+  - thinking-models-planning.md
+  - thinking-models-debug.md
+  - git-integration.md
+  - git-planning-commit.md
+  - state-schema.md
+  - karpathy-guidelines.md
+  - no-unauthorized-git-ops.md
+  - questioning.md
+  - domain-probes.md
+  - ui-brand.md

package/rihal/modules/discovery.yaml

@@ -0,0 +1,50 @@
+name: discovery
+version: "1.0"
+description: "Project discovery — new-project, map-codebase, scan, explore, code-review, docs-update"
+requires:
+  - core
+agents:
+  - rihal-codebase-mapper.md
+  - rihal-project-researcher.md
+  - rihal-roadmapper.md
+  - rihal-phase-researcher.md
+  - rihal-advisor-researcher.md
+  - rihal-assumptions-analyzer.md
+  - rihal-research-synthesizer.md
+workflows:
+  - new-project.md
+  - map-codebase.md
+  - scan.md
+  - explore.md
+  - code-review.md
+  - code-review-fix.md
+  - secure-phase.md
+  - docs-update.md
+  - discuss-phase-power.md
+  - create-epics-and-stories.md
+  - create-story.md
+  - dev-story.md
+  - document-project.md
+  - ui-phase.md
+  - ui-review.md
+commands:
+  - new-project.md
+  - map-codebase.md
+  - scan.md
+  - explore.md
+  - code-review.md
+  - code-review-fix.md
+  - secure-phase.md
+  - docs-update.md
+  - discuss-phase-power.md
+  - create-epics-and-stories.md
+  - create-story.md
+  - dev-story.md
+  - document-project.md
+  - ui-phase.md
+  - ui-review.md
+references:
+  - checklist-architect.md
+  - checklist-change.md
+  - verification-patterns.md
+  - tdd.md

package/rihal/modules/execution.yaml

@@ -0,0 +1,66 @@
+name: execution
+version: "1.0"
+description: "Plan execution — write and run PLAN.md files, quick tasks, debug, audit-fix"
+requires:
+  - core
+agents:
+  - rihal-executor.md
+  - rihal-planner.md
+  - rihal-verifier.md
+  - rihal-debugger.md
+  - rihal-sprint-checker.md
+  - rihal-integration-checker.md
+  - rihal-nyquist-auditor.md
+workflows:
+  - execute.md
+  - plan.md
+  - list-plans.md
+  - quick.md
+  - debug.md
+  - audit-fix.md
+  - undo.md
+  - analyze-dependencies.md
+  - import.md
+  - inbox.md
+  - check-implementation-readiness.md
+  - correct-course.md
+  - code-review.md
+  - code-review-fix.md
+  - review-adversarial.md
+  - review-edge-case-hunter.md
+  - chain.md
+  - export-to-github.md
+commands:
+  - execute.md
+  - plan.md
+  - list-plans.md
+  - quick.md
+  - debug.md
+  - audit-fix.md
+  - undo.md
+  - analyze-dependencies.md
+  - import.md
+  - inbox.md
+  - check-implementation-readiness.md
+  - correct-course.md
+  - code-review.md
+  - code-review-fix.md
+  - review-adversarial.md
+  - review-edge-case-hunter.md
+  - chain.md
+  - export-to-github.md
+references:
+  - execution-protocol.md
+  - checkpoints.md
+  - continuation-format.md
+  - output-format.md
+  - output-realism.md
+  - verification-patterns.md
+  - tdd.md
+  - checklist-story-draft.md
+  - checklist-story-dod.md
+  - checklist-po-master.md
+  - checklist-architect.md
+  - checklist-change.md
+  - checklist-pm.md
+  - karpathy-guidelines.md

package/rihal/references/brain-methods.csv

@@ -0,0 +1,9 @@
+name,description,steps,output-format
+SCAMPER,Systematic idea generation by applying 7 transformations to an existing product/feature,"1. List the current product/feature in detail. 2. For each letter (Substitute/Combine/Adapt/Modify/Put-to-other-uses/Eliminate/Reverse), ask ""what if we...?"" 3. Generate one idea per transformation. 4. Combine promising ideas.","Markdown list: one idea per transformation, brief rationale for each"
+Random Stimulus,Break linear thinking by introducing unrelated objects/words and forcing connections,"1. Pick a random word from a list (or use a random object in the room). 2. Free-associate: how is this like our problem? 3. Stretch: connect it to the problem, no matter how absurd. 4. Refine absurd ideas into viable concepts.","Markdown: Stimulus word → Association → Absurd idea → Refined concept"
+Reverse Brainstorm,Generate ideas for the opposite problem (how to destroy/worsen/fail) then flip them,"1. Restate goal as its opposite (""How to INCREASE churn instead of reduce?""). 2. Generate ideas for the bad outcome. 3. For each bad idea, write the opposite as a solution.","Two-column markdown table: Bad idea / Good idea (flip)"
+Brainwriting,Silent written ideation followed by sequential refinement (avoids groupthink),"1. Each person writes 3-5 initial ideas on a sheet or document. 2. Pass it to the next person who adds to or refines. 3. Rotate 3-4 rounds. 4. Synthesize the evolved ideas.","Markdown list with iteration markers showing how ideas evolved: Idea (Round 1) → Refinement (Round 2) → Final"
+6-3-5,Structured brainwriting for teams: 6 people, 3 ideas each, 5 rounds,"1. 6 people, each writes 3 ideas in 5 minutes. 2. Pass to the right. 3. Next person improves or extends those 3 ideas (5 minutes). 4. Repeat 5 times. 5. Final sheet has 18 ideas, each evolved 5 times.","Markdown 6x3 matrix: rows are idea streams, columns are rounds, each cell shows the idea's evolution"
+Mind Mapping,Radial idea structure with main idea at center and branches for sub-ideas,"1. Write the core problem/goal in the center. 2. Draw branches for main themes. 3. Add sub-branches for details. 4. Use images, colors, single words per node. 5. Connect related nodes across branches.","ASCII art or text outline with indentation showing hierarchy: Core → Main branches → Sub-branches"
+Starbursting,Exploratory questions (Who/What/When/Where/Why/How) frame the problem space,"1. Identify the subject (product/feature/problem). 2. Ask Who/What/When/Where/Why/How. 3. For each question, generate 3-5 sub-questions. 4. Ideas emerge from the answer space you've charted.","Markdown with 6 sections (one per reporter question), each containing a list of generated sub-questions and emerging ideas"
+Rolestorming,Adopt a persona (customer/competitor/expert/outsider) and generate ideas from their perspective,"1. Choose a persona (e.g., 10-year-old user, competitor CEO, alien anthropologist, luddite). 2. Ask: what would X think about our problem? 3. Generate 5-10 ideas from that lens. 4. Repeat with 2-3 other personas.","Markdown sections by persona: [Persona name] → Ideas from this perspective (bulleted list)"

package/rihal/references/checklist-architect.md

@@ -0,0 +1,146 @@
+# Checklist: Architecture Decision Checklist
+
+Use this checklist when **making a significant technical decision** — choosing libraries, refactoring layers, picking a pattern, introducing a new service.
+
+This prevents "let's just try it and see" decisions that cause rework.
+
+## Current State Documented
+
+- [ ] **Existing stack listed** — What tech do we currently use?
+  - Backend framework, ORM, auth library, caching, queues, etc.
+  - If you're not sure, ask CTO or read the CLAUDE.md and existing code
+- [ ] **Why it exists** — What problem does the current stack solve?
+  - "Using Next.js because: SSR benefits, developer experience, integrated routing"
+  - Not: "That's what we've always used"
+- [ ] **Constraints documented** — What can't we change?
+  - Team expertise ("No Rust; we only know Python/JS")
+  - Performance targets ("Must handle 10k req/sec")
+  - Compliance ("Must be EU-hosted due to GDPR")
+  - Cost ("Can't use Google Cloud; locked into AWS")
+
+## Real Constraint Identified
+
+- [ ] **NOT a preference** — This is a genuine blocker, not "I like X better"
+  - Constraint: "Current auth library doesn't support OIDC; customers require it"
+  - Preference: "I've heard Passport is trendy"
+- [ ] **Evidence gathered** — Why can't we use the current approach?
+  - Performance test showing current library fails at load
+  - Customer requirement documented
+  - Security audit finding a vulnerability
+  - Team observation: "We've spent 20% of last 3 sprints fighting this library"
+
+## Options Explored (2-3 Alternatives)
+
+- [ ] **Option A** — Approach with pros/cons, fit, effort
+  - Example: "Upgrade to jose v5 (our current library)"
+    - Pros: No new dependency, team knows it
+    - Cons: Missing feature we need (OIDC)
+    - Effort: 2 days research + test
+    - Fit: Doesn't solve core constraint
+    
+- [ ] **Option B** — Alternative approach
+  - Example: "Switch to Passport.js + passport-oidc strategy"
+    - Pros: Industry standard, OIDC support, large ecosystem
+    - Cons: New dependency, learning curve, 2 new vulnerabilities in 2024 (but patched)
+    - Effort: 1 week to migrate + test
+    - Fit: Fully solves OIDC requirement
+    
+- [ ] **Option C** — Radical alternative or do-nothing
+  - Example: "Partner with auth0 (outsource instead of building)"
+    - Pros: Eliminates ongoing maintenance, compliance built-in
+    - Cons: Vendor lock-in, $5k/month cost, new infrastructure
+    - Effort: 3 days to integrate
+    - Fit: Solves OIDC + reduces team burden
+
+## Load-Bearing Assumptions Listed
+
+- [ ] **What must be true for this decision to work?**
+  - "Option B assumes Passport.js ecosystem doesn't have breaking changes in next 2 years"
+  - "Assumes team has 1 week to dedicate to migration"
+  - "Assumes 100k user base doesn't create edge cases we haven't tested"
+- [ ] **How will we know if assumptions break?**
+  - "Monitor Passport.js changelog; if 3+ critical vulnerabilities found in 6 months, reconsider"
+  - "If migration takes >8 days, pivot to Option A and accept OIDC limitation"
+
+## Kill-Switch Defined
+
+- [ ] **When would we rollback?**
+  - "If migration breaks production auth for >10 minutes"
+  - "If new library causes >20% performance regression"
+  - "If team spends >3 days on unexpected bugs"
+- [ ] **Rollback plan documented** — How do we undo this?
+  - "Keep old library in git history; we can revert in 1 hour"
+  - "Proxy both auth systems for 1 week during migration"
+
+## ADR Written
+
+- [ ] **ADR file created at `.planning/adrs/YYYYMMDD-{slug}.md`**
+
+Format:
+```markdown
+# ADR-001: Switch to Passport.js for OIDC Support
+
+## Status
+Accepted (date: 2026-04-12)
+
+## Context
+Current auth library (jose) doesn't support OIDC. 3 customers requested OIDC support in last 2 months. Estimated revenue impact: $50k ARR.
+
+## Decision
+Adopt Passport.js + passport-oidc for authentication.
+
+## Consequences
+- Positive: OIDC support, industry standard, 10k GitHub stars
+- Negative: New dependency, migration effort (1 week), team learning curve
+- Rollback: Keep old code in git, revert if migration takes >8 days
+
+## Kill Criterion
+Stop migration if:
+- Performance drops >20%
+- Production outage >10 minutes
+- Bugs found in >3 new tests
+
+## Reviewed By
+CTO, Product Owner, QA Lead
+```
+
+## Template Checklist
+
+```markdown
+## Decision: [Feature/Library/Pattern]
+
+**Current Stack:** [What we use now and why]
+
+**Constraint:** [Why we can't keep using it]
+
+**Options:**
+- [ ] A: [Option with fit/effort/pros/cons]
+- [ ] B: [Option with fit/effort/pros/cons]
+- [ ] C: [Option with fit/effort/pros/cons]
+
+**Assumptions:**
+- [ ] If [X], then this works
+- [ ] We can verify by [measurement]
+
+**Kill Switch:** Stop if [condition]
+
+**Rollback:** [How to undo in <1 hour]
+
+**ADR:** `.planning/adrs/YYYYMMDD-slug.md`
+
+**Status:** ✓ Decided (Passport.js)
+```
+
+## When NOT to Use This Checklist
+
+- Small tactical decisions: "Should we use const or let?" → Use linter
+- Reversible decisions: "What CSS utility library?" → Try it, swap if needed
+- Greenfield projects: Follow checklist but options can be lighter
+
+## When to ALWAYS Use This Checklist
+
+- New library adoption
+- Framework upgrade/replacement
+- Major refactoring (splitting monolith, new service)
+- Switching cloud providers or databases
+- New architectural pattern (events, CQRS, microservices)

package/rihal/references/checklist-change.md

@@ -0,0 +1,136 @@
+# Checklist: Before Changing Existing Code
+
+Use this checklist when **modifying an existing module, function, or component** — refactoring, bug fixing, or extending existing functionality.
+
+This prevents breaking changes that sneak into production.
+
+## Baseline Understanding
+
+- [ ] **Read existing tests first** — What behavior is being tested?
+  - Copy test names/assertions to your notes
+  - If no tests exist, write tests for current behavior BEFORE changing anything
+  - Why: Tests document the contract. Changing code without knowing the contract causes regressions
+  
+- [ ] **Read recent commits** — Why was this code written this way?
+  - `git log -p --follow -- src/auth.ts` (last 5 commits)
+  - Look for edge case fixes, performance optimizations, security patches
+  - Why: Old commits often document why a seemingly-odd choice was made
+
+- [ ] **Understand the data flow** — How does data move through this code?
+  - Draw a simple diagram: inputs → processing → outputs
+  - Track transformations: what format does data start in, what format does it end as?
+  - Why: Breaking a transformation silently breaks downstream code
+
+## Regression Risk Assessment
+
+- [ ] **Identified what this code is used by** — What calls it?
+  - `grep -r "functionName\|ClassName" --include="*.ts" --include="*.js" .`
+  - Count: how many places depend on this?
+  - Risk: 1 call site = low risk. 20+ call sites = high risk.
+  
+- [ ] **Named the breaking-change risk** — If this behavior changes, what breaks?
+  - "This function is called by 5 API endpoints. If return type changes, all 5 break."
+  - "This component is used in 3 pages. If props signature changes, all 3 break."
+  - Why: Forces you to consider impact before changing
+
+- [ ] **Confirmed backward compatibility** — Can old callers still work?
+  - "Old API calls will still get valid response (new fields ignored)"
+  - "Component props are additive (optional, don't break existing usage)"
+  - "Database schema migration is non-breaking (old code ignores new column)"
+
+## Rollback Planning
+
+- [ ] **Defined rollback path** — How do we undo this if it breaks?
+  - "Revert commit, redeploy previous version (5 min)"
+  - "Feature flag to disable new code path (instant)"
+  - "Database schema migration is reversible (downtime: 2 min)"
+  - Why: If you can't explain rollback in <5 minutes, the change is too risky
+
+- [ ] **Identified rollback entry point** — Where do we pull the lever?
+  - "Kill switch in .env variable" → document the var name and values
+  - "Feature flag in admin panel" → provide exact steps
+  - "Git revert" → specify which commits to revert
+  - Why: Under stress, ops person needs a clear lever to pull
+
+## Testing Strategy
+
+- [ ] **Minimum viable test suite specified** — What MUST pass?
+  - Existing tests for modified code MUST still pass (regression tests)
+  - New tests for new behavior (if adding features)
+  - Integration tests if this touches API boundaries or data flow
+  - Why: Prevents shipping tests that pass but don't catch regressions
+
+- [ ] **Test edge cases first** — What breaks easily?
+  - Null inputs, empty collections, boundary values
+  - Concurrent calls, race conditions
+  - Large inputs (performance)
+  - Why: Edge cases are where regressions hide
+
+- [ ] **Performance regression tested** — Is it slower?
+  - If code touches hot path: benchmark before/after
+  - If code touches database: check query count
+  - If code touches network: check request count
+  - Why: Slow deployments are silent killers
+
+## Change Scope
+
+- [ ] **Limited to the stated change** — Am I changing more than needed?
+  - Good: Fix the bug, leave formatting alone
+  - Bad: Fix the bug AND refactor 5 functions AND reorder imports
+  - Why: Scope creep makes review harder and causes regressions in unexpected places
+
+- [ ] **Commit atomicity** — Is this one logical change?
+  - One bug fix = one commit
+  - One feature = one commit (or a few if very large)
+  - Don't mix refactoring with bug fixes
+  - Why: Bisect and revert are easier with atomic commits
+
+## Template Checklist
+
+```markdown
+## Change: [What you're changing]
+
+**File(s):** [Paths affected]
+
+### Baseline
+- [x] Read existing tests: [test names that document current behavior]
+- [x] Recent commits reviewed: [commits 1, 2, 3 and why they matter]
+- [x] Data flow understood: [diagram or description]
+
+### Regression Risk
+- [x] Call sites identified: [5 API endpoints use this function]
+- [x] Breaking risk: [If return type changes, all 5 callers break]
+- [x] Backward compat: [New fields are optional; old code ignores them]
+
+### Rollback Plan
+- [x] Rollback: [Revert commit ABC123; redeploy]
+- [x] Time to rollback: [5 minutes]
+- [x] Kill switch: [Feature flag ENABLE_NEW_AUTH in .env]
+
+### Testing
+- [x] Regression tests: [Existing 12 tests for auth.ts still pass]
+- [x] Edge cases: [Null user, expired token, rate-limited]
+- [x] Performance: [Query count: before 3, after 3 (no regression)]
+
+### Scope
+- [x] Limited to stated change: [Only fixing the bug, not refactoring]
+- [x] Atomic commit: [One logical change per commit]
+
+**Ready to ship:** ✓ Yes
+```
+
+## Red Flags — STOP Before Committing
+
+- ❌ Can't explain rollback path in 1 sentence
+- ❌ More than 30% of test file modified (likely changing contract)
+- ❌ >10 files changed for a single feature (too much scope)
+- ❌ Breaking change has no migration plan documented
+- ❌ No test coverage added for new behavior
+- ❌ Performance regression >10% (benchmark before/after)
+- ❌ "I'll fix this edge case later" (fix it now or document it as a stub)
+
+If you hit a red flag, STOP. Either:
+1. Narrow the scope (fix less)
+2. Add a migration plan (if breaking)
+3. Split into multiple commits (if too large)
+4. Document edge cases (if intentional stubs)