@hanzlaa/rcode 2.1.0

package/rihal/references/checklist-pm.md

@@ -0,0 +1,154 @@
+# Checklist: Product Manager Pre-Execution Checklist
+
+Use this checklist as a **Product Manager or execution lead** deciding whether a story/epic is **ready to execute** (all dependencies gathered, team aligned, blockers cleared).
+
+This gate happens RIGHT BEFORE execution (after planning, before dev work starts).
+
+## Market & Customer Evidence
+
+- [ ] **Market research complete** — Do we know customer need?
+  - Mariam (Growth) completed discovery: surveys, competitor analysis, use case documentation
+  - Reference: `.planning/research/[feature-name]-market-analysis.md`
+  - Output: "10 potential customers need X", "Current gap in market"
+  
+- [ ] **Customer validation** — Have we talked to actual users?
+  - "5 customers asked for this in last 6 months"
+  - "Support tickets: 20+ about this issue"
+  - NOT: "We think users would like this"
+
+- [ ] **Business case documented** — What's the revenue/retention impact?
+  - "Estimated $50k ARR impact if we build"
+  - "Reduces churn by 5% (12 customers @ $5k each = $60k)"
+  - "Unblocks 3 enterprise deals stuck on this feature"
+
+## Scope & Story Definition
+
+- [ ] **Scope defined** — What's in, what's out?
+  - User stories written following checklist-story-draft
+  - MoSCoW prioritization applied (Must, Should, Could, Won't)
+  - Out-of-scope list prevents creep
+  
+- [ ] **Acceptance criteria clear** — Can QA verify completion?
+  - All stories have 3+ acceptance criteria
+  - Each criterion is testable (not vague)
+  - Reference: User stories in `.planning/stories/[feature-name].md`
+
+- [ ] **Dependencies mapped** — What do we need first?
+  - "This feature depends on API endpoint from backend team (eta: 2026-04-15)"
+  - "Requires design approval from Layla (scheduled for 2026-04-10)"
+  - "Blocks downstream feature: user preferences (can start after this ships)"
+
+## Technical Feasibility
+
+- [ ] **Waleed (CTO) confirmed feasible** — Is the architecture possible?
+  - "Reviewed architecture; can be done with current stack"
+  - "No blocking unknowns"
+  - Reference: `.planning/technical-feasibility/[feature-name].md`
+
+- [ ] **Tech debt considered** — Does this create problems?
+  - "Will need refactoring in area X (planned for Q3)"
+  - "No new security issues"
+  - "Performance impact assessed: <5% overhead"
+
+- [ ] **Dependencies available** — Do we have what we need?
+  - "All required libraries exist and are maintained"
+  - "No new tooling needed" OR "New tools procured and tested"
+  - "Environment setup documented"
+
+## QA & Quality Gates
+
+- [ ] **Fatima (QA Lead) signed off** — Can we test this thoroughly?
+  - "Test plan created: 15 manual test cases + 20 automated tests"
+  - "Performance regression tests specified"
+  - "Security tests identified (if applicable)"
+  - Reference: `.planning/qa/[feature-name]-test-plan.md`
+
+- [ ] **Release gate defined** — What makes this shippable?
+  - "All acceptance criteria passed"
+  - "Zero critical bugs, <5 P2 bugs"
+  - "Performance benchmarks met (load test: 1k users/sec)"
+  - "No console.log left; no TODO comments"
+
+- [ ] **Rollback tested** — Can we undo this?
+  - "Database migration is reversible"
+  - "Feature flag allows instant disable"
+  - "Rollback tested; confirmed takes <5 min"
+
+## Strategic Alignment
+
+- [ ] **Kill criterion from Sadiq (Strategy)** — When would we stop?
+  - "If implementation exceeds 3 weeks, defer to Q3"
+  - "If performance regression >10%, reconsider approach"
+  - "If customer feedback shows demand is lower than expected"
+
+- [ ] **Roadmap impact clear** — What else does this affect?
+  - "Delays bug fixes by 1 week" OR "Doesn't delay roadmap"
+  - "Unblocks 3 other features"
+  - "Team capacity confirmed: 2 people, 3 weeks"
+
+## Customer Handoff
+
+- [ ] **First customer named** — Who gets this first?
+  - "Mariam identified 3 beta customers; Mariam (customer) is priority #1"
+  - "Rollout plan: beta with 3 customers first, then all users"
+  - "Communication plan: send announcement on 2026-05-01"
+
+- [ ] **Success metrics defined** — How do we measure impact?
+  - "Target: 10+ customers using feature in first month"
+  - "Target: <2 support tickets about this feature after launch"
+  - "Target: NPS score increase by 2 points in follow-up survey"
+
+## Sign-Off Gate
+
+This story is **READY TO EXECUTE** when:
+
+```markdown
+## Pre-Execution Sign-Off
+
+✓ Market research complete (Mariam)
+✓ Scope defined with MoSCoW (Hussain-PM)
+✓ Technical feasibility confirmed (Waleed)
+✓ QA test plan ready (Fatima)
+✓ Strategy/kill criterion from Sadiq
+✓ First customer identified (Mariam)
+
+**Status:** Ready to start execution on 2026-04-15
+**Estimated completion:** 2026-05-01
+**Expected impact:** +$50k ARR, 5% churn reduction
+```
+
+Story is **NOT READY** if any of:
+- Stakeholder missing (no Mariam research, no Waleed feasibility)
+- Scope fuzzy ("nice to have" or unclear acceptance criteria)
+- No customer identified
+- No rollback plan
+- Kill criterion missing
+
+## Template
+
+```markdown
+# Pre-Execution Checklist: [Feature Name]
+
+## Market & Customer
+- [x] Market research: [Mariam's doc path] — 10 customers need this
+- [x] Customer validation: [Support tickets + survey feedback]
+- [x] Business case: [$50k ARR impact, 5% churn reduction]
+
+## Scope
+- [x] Stories written: [Count and link to stories]
+- [x] MoSCoW applied: Must (8), Should (3), Could (2)
+- [x] Dependencies: [Backend API ready by 2026-04-15]
+
+## Technical
+- [x] Feasibility: [Waleed approved] — no blocking unknowns
+- [x] Architecture: [No new tech, fits current patterns]
+- [x] QA plan: [Fatima: 15 manual + 20 automated tests]
+
+## Strategy
+- [x] Kill criterion: [Stop if >3 weeks or >10% perf regression]
+- [x] Roadmap impact: [Delays bug fixes 1 week]
+- [x] Rollout plan: [Beta with 3 customers, then all users]
+
+## Status
+✓ Ready to execute on 2026-04-15
+```

package/rihal/references/checklist-po-master.md

@@ -0,0 +1,100 @@
+# Checklist: Product Owner Master Checklist
+
+Use this checklist as a **Product Owner (or product lead)** deciding whether to **start work on a story or epic**.
+
+This is the gate before planning or execution. If you cannot check all items, the work is not ready to start.
+
+## Stakeholder Alignment
+
+- [ ] **Who asked?** — Named stakeholder (not "the team", but "Mariam wants X" or "customer complaint #42")
+  - If internal: Which team member? What's their role?
+  - If external: Which customer? What's their use case?
+- [ ] **Why now?** — Evidence the ask is urgent or has high impact
+  - Market research data? Customer churn risk? Competitive pressure? Roadmap dependency?
+  - Not: "Someone mentioned it"
+
+## Problem & Impact
+
+- [ ] **What gets worse if we DON'T build this?** — Be specific
+  - Bad: "Users will be unhappy"
+  - Good: "We lose 5+ customers per month due to missing export feature. Support tickets about this: 12/month."
+- [ ] **Measurable outcome** — How will we know success?
+  - "Reduce support tickets about this feature from 12/month to <2/month"
+  - "Increase user retention by 3% in Q2"
+  - "Enable 10 new enterprise customers who require SSO"
+
+## Scope Boundary
+
+- [ ] **Kill criterion defined** — When would we stop building this?
+  - "If implementation requires breaking existing API contracts"
+  - "If cost exceeds $50k in infrastructure changes"
+  - "If we discover >30% of users don't use the feature after 2 weeks"
+- [ ] **Opportunity cost named** — What ELSE are we not doing?
+  - "We ship this, we delay bug fixes by 2 weeks"
+  - "This takes 3 people for 1 sprint = 1 sprint delay on roadmap"
+
+## Decision Criteria
+
+- [ ] **Effort estimated** — Do we know roughly how long?
+  - Work with CTO/architect: "This is probably a 2-3 week story" or "This needs deeper research first"
+- [ ] **Risk identified** — What could go wrong?
+  - "Depends on new vendor library (not battle-tested)"
+  - "Requires database schema migration (rollback risk)"
+  - "Affects 40% of users; bugs here are high-impact"
+- [ ] **Alternatives considered** — Is building the only option?
+  - "Could we fix this with a workaround instead?"
+  - "Could we partner/integrate instead of building?"
+  - "Could we defer this 1 quarter and see if the ask goes away?"
+
+## Readiness Gate
+
+✅ **Ready to plan/execute** when:
+- All items checked
+- Stakeholder has approved the kill criterion
+- Team capacity confirmed
+
+❌ **Not ready** when:
+- Stakeholder is unclear
+- Problem statement is vague
+- Kill criterion missing (scope will creep)
+- Opportunity cost not discussed with team
+
+## Template
+
+```markdown
+## Work: [Feature Name]
+
+**Stakeholder:** [Name, role, evidence they asked]
+
+**Problem:** What gets worse if we don't build this?
+- [Specific, measurable impact]
+- [Data point supporting urgency]
+
+**Success Metric:** How will we know this worked?
+- [Measurable outcome]
+
+**Kill Criterion:** When would we stop?
+- [Specific condition that stops work]
+
+**Opportunity Cost:** What are we NOT doing?
+- [Team capacity impact]
+- [Roadmap delay]
+
+**Estimated Effort:** [S | M | L] — [Why this size]
+
+**Risks:**
+- [Risk 1]
+- [Risk 2]
+
+**Status:** ✓ Ready to plan
+```
+
+## When to Say "Not Ready"
+
+1. **Stakeholder vague:** "Add notifications" without naming who asked or why
+2. **Impact unclear:** "Would be nice to have" with no data
+3. **Kill criterion missing:** Will expand forever
+4. **Opportunity cost unknown:** Team doesn't know what they're delaying
+5. **Risk not discussed:** Building on untested foundation
+
+In these cases, ask for a council or discovery session before committing to work.

package/rihal/references/checklist-story-dod.md

@@ -0,0 +1,75 @@
+# Checklist: Story Definition of Done
+
+Use this checklist when **completing a user story** — all acceptance criteria met, code written, tests passing.
+
+A story is "Done" only when all these items are checked:
+
+## Acceptance Criteria Verification
+
+- [ ] **All acceptance criteria met** — Each criterion tested and passing
+  - For UI: User can perform the action and see expected result
+  - For API: Endpoint returns correct status and response shape
+  - For Data: Stored/retrieved data is accurate
+- [ ] **Edge cases handled** — Empty states, errors, boundary conditions work correctly
+- [ ] **No known stubs** — No TODO comments, empty function bodies, or placeholder values left in code
+
+## Testing
+
+- [ ] **Tests written** — Unit tests for logic, integration tests for workflows
+- [ ] **All tests passing** — No failures, flaky tests fixed
+- [ ] **Coverage adequate** — Critical paths have test coverage (aim for 80%+ on modified code)
+
+## Code Quality
+
+- [ ] **No lint errors** — Code style follows project conventions (from CLAUDE.md or equivalent)
+- [ ] **No console.log left** — Debug logs removed from production code (tests may have logging)
+- [ ] **Follows project patterns** — Uses existing architecture, naming, folder structure
+- [ ] **Imports correct** — All dependencies exist and are installed
+
+## Documentation
+
+- [ ] **Code commented** — Complex logic explained; edge cases documented
+- [ ] **API documented** — Endpoints have request/response examples (if API story)
+- [ ] **UI behavior documented** — States and interactions clear for maintainers
+
+## Commits
+
+- [ ] **Conventional Commits format** — `type(scope): description` (e.g., `feat(auth): add JWT refresh rotation`)
+- [ ] **No AI attribution** — No "Generated with Claude Code", no "Co-Authored-By: Claude"
+- [ ] **Meaningful messages** — Why the change, not just what changed
+- [ ] **One logical change per commit** — Not mixing unrelated work
+
+## State & Handoff
+
+- [ ] **Story summary written** — Brief recap of what was built (for PR or SUMMARY.md)
+- [ ] **State updated** — If this is part of a plan, SUMMARY.md created
+- [ ] **No blockers recorded** — If blockers exist, they're documented for team
+
+## Definition of Done Template
+
+```markdown
+## Acceptance Criteria Verification
+- [x] All 5 criteria tested and passing
+- [x] Edge cases: empty posts list, network error, 404 user
+
+## Testing
+- [x] 12 new tests written (POST, GET, error cases)
+- [x] All tests passing locally and in CI
+- [x] Coverage: auth module at 87%
+
+## Code Quality
+- [x] Zero lint errors
+- [x] Follows existing .../api/routes pattern
+- [x] Using existing jwt library (jose)
+
+## Commits
+- [x] feat(auth): add JWT refresh token rotation
+- [x] test(auth): add refresh token tests
+```
+
+## When NOT All Items Are Checked
+
+If any item cannot be checked:
+1. **Add a blocker:** Record why it's blocked (missing dependency, design uncertainty, etc.)
+2. **Split the story:** If too much work remains, move non-critical acceptance criteria to a new story
+3. **Flag for review:** Bring to team (council/standup) before merging

package/rihal/references/checklist-story-draft.md

@@ -0,0 +1,53 @@
+# Checklist: Story Draft
+
+Use this checklist when **writing the first draft of a user story** — before it enters the backlog or gets assigned.
+
+## Story Structure
+
+- [ ] **User persona named** — Not "user", but "Mariam (Marketing Lead)" or "Waleed (CTO)" or "Agent deploying to production"
+- [ ] **Action/outcome specified** — Clear verb: "view", "export", "validate", "retry", not vague "manage" or "handle"
+- [ ] **Acceptance criteria (3+ bullets)** — Each criterion is testable, not subjective
+  - Good: "Users can filter by date range using calendar widget, showing only posts from selected dates"
+  - Bad: "System should be fast"
+- [ ] **Out-of-scope explicitly listed** — What the story does NOT do (prevents scope creep)
+- [ ] **Effort estimate (S/M/L)** — Story points or t-shirt size for capacity planning
+  - S = 1-2 days, M = 3-5 days, L = 1+ weeks
+
+## Template
+
+```markdown
+# Story: [Action for Persona]
+
+**Persona:** [Name, role, context]
+
+**Action:** As a [persona], I want to [action] so that [outcome/benefit].
+
+## Acceptance Criteria
+
+- [ ] [Testable condition 1]
+- [ ] [Testable condition 2]
+- [ ] [Testable condition 3]
+
+## Out of Scope
+
+- [What this story does NOT do]
+- [What will be in a future story]
+
+## Effort
+
+**Estimate:** [S | M | L]
+**Rationale:** [why this size]
+
+## Notes
+
+[Any research, design decisions, or open questions]
+```
+
+## Passing the Draft Check
+
+A story is ready to move forward when:
+1. Persona is named and rooted in the actual team
+2. Acceptance criteria are independently verifiable
+3. Out-of-scope list prevents misunderstanding
+4. Estimate is realistic (check with implementer if uncertain)
+5. Story fits in one sprint/phase (if L estimate, consider splitting)

package/rihal/references/checkpoints-index.md

@@ -0,0 +1,53 @@
+# Checkpoints — Quick Reference
+
+Plans execute autonomously. Checkpoints formalize interaction points where human verification or decisions are needed.
+
+**Core principle:** the agent automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+
+## Golden Rules
+
+1. **If the agent can run it, the agent runs it** - Never ask user to execute CLI commands, start servers, or run builds
+2. **The agent sets up the verification environment** - Start dev servers, seed databases, configure env vars
+3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
+4. **Secrets come from user, automation comes from the agent** - Ask for API keys, then the agent uses them via CLI
+5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow._auto_chain_active` or `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+
+## Checkpoint Types
+
+| Type | Frequency | Use Case |
+|------|-----------|----------|
+| **human-verify** | 90% | Agent completed work, human confirms it's correct (visual checks, testing) |
+| **decision** | 9% | Human must choose between options (tech selection, architecture, design) |
+| **human-action** | 1% | Authentication gates or email verification links |
+
+## Most Common Pattern: human-verify
+
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[What the agent automated and deployed]</what-built>
+  <how-to-verify>[Exact steps to test - URLs, commands, expected behavior]</how-to-verify>
+  <resume-signal>[How to continue - "approved", "yes", or describe issues]</resume-signal>
+</task>
+```
+
+**Use for:**
+- Visual UI checks (layout, styling, responsiveness)
+- Interactive flows (click through wizard, test user flows)
+- Functional verification (feature works as expected)
+- Audio/video playback quality
+- Animation smoothness
+- Accessibility testing
+
+## Execution Protocol
+
+When the agent encounters `type="checkpoint:*"`:
+
+1. **Stop immediately** - do not proceed to next task
+2. **Display checkpoint clearly** using checkpoint format
+3. **Wait for user response** - do not hallucinate completion
+4. **Verify if possible** - check files, run tests, whatever is specified
+5. **Resume execution** - continue to next task only after confirmation
+
+## Full Details
+
+For complete checkpoint examples, auth gate patterns, and decision-making templates, see `/rihal/references/checkpoints.md` (detailed reference with 30+ examples).