@hanzlaa/rcode 3.6.14 → 3.6.16

package/rihal/references/agent-contracts.md

@@ -1,22 +1,48 @@
 # Agent Contracts
 
-Conventions Rihal sub-agents follow when invoked from a workflow.
-
-- **Input**: a single prompt string. The orchestrator passes structured data
-  inline (path lists, JSON blobs) — sub-agents do not stream args.
-- **Output**: one final message back to the orchestrator. No partial state
-  is visible mid-run.
-- **Side effects**: each agent's tool list is its full surface — any tool
-  not granted in the agent definition is unavailable.
-- **Failure**: agents that hit an obstacle return a structured "blocked"
-  message rather than fabricating output.
-
-## Iterative retrieval (research subagents)
-
-When a workflow spawns a research subagent, it passes the broader objective —
-not just the literal query — and evaluates the returned result for sufficiency
-against that objective. If the result is insufficient (coverage gap, vague
-recommendations, or a blocked signal), the workflow re-dispatches the same
-subagent with the named gaps, hard-capped at 3 cycles. This loop is research-only
-— it does not apply to executor subagents. See `iterative-retrieval.md` for the
-full contract.
+Every Rihal agent and skill operates under a contract that defines what it consumes, what it produces, and what guarantees it offers. Workflows depend on these contracts being honoured — if an agent silently broadens or narrows its contract, the orchestrator's assumptions break.
+
+## The contract has 5 parts
+
+1. **Inputs** — what the orchestrator passes to the agent at spawn time. Examples: phase number, sprint id, story file path, council question, file glob.
+2. **Outputs** — concrete artifacts produced. Always file paths or structured JSON, never free-form prose. Examples: `SUMMARY.md`, `RESEARCH.md`, a `state.json` mutation, a JSON object on stdout.
+3. **Side effects** — what the agent writes outside its primary output. Examples: state.json upserts, .planning/ artifacts, decisions log entries.
+4. **Halt conditions** — when the agent stops and returns control. Examples: menu reached, user input required, blocker detected, budget exhausted.
+5. **Failure modes** — what the agent does on error. Always: partial output is preserved, error is reported with a fix command, exit code is non-zero.
+
+## Contract enforcement
+
+- Every agent's `.md` file declares its inputs/outputs in the frontmatter or opening section.
+- Workflows that spawn agents pass exactly the declared inputs — no more, no less.
+- Orchestrators verify the declared outputs after the agent returns. Missing output = run failed, regardless of what the agent says.
+- Side-effect changes (state.json, .planning/) are validated against `_shared/state-sync-rule.md`.
+
+## Why this matters
+
+Without contracts, agents drift. An agent originally designed to "read code and produce SUMMARY.md" starts also writing decisions and modifying state.json. The next workflow that spawns it makes assumptions that no longer hold. Cascading silent breakage.
+
+The contract is the API. Treat agents like network services that happen to run in-process.
+
+## When you write a new agent
+
+Open with a contract block:
+
+```yaml
+---
+name: rihal-foo
+inputs:
+  - phase: NN
+  - story_path: .planning/phases/NN/story-X.md
+outputs:
+  - .planning/phases/NN/story-X-SUMMARY.md
+side_effects:
+  - state.phases[N].stories[X].status: completed
+halt_conditions:
+  - acceptance criteria not measurable
+  - user-input required for design decision
+on_failure:
+  - emit FAILURE.md with diagnostic + suggested fix command
+---
+```
+
+If your agent doesn't fit a contract, the agent is too broad — split it.

package/rihal/references/model-profile-resolution.md

@@ -1,8 +1,44 @@
 # Model Profile Resolution
 
-Workflows pick a model via `node .rihal/bin/rihal-tools.cjs resolve-model
-<role>`, which reads `.rihal/config.yaml` `model_profile` and returns the
-concrete model id for that role per `rihal/config/model-profiles.json`.
+Rihal Code lets each project pick a `model_profile` in `.rihal/config.yaml`. The profile decides which Claude model each spawned agent uses.
 
-If `model_profile` is unset, default is `balanced`. Unknown profile falls
-back to `balanced` with a stderr warning.
+## Profiles
+
+| Profile | When to pick | Model assignment |
+|---------|--------------|------------------|
+| `quality` | Critical milestone, hard problem, high blast radius | Most agents → Opus; tactical sub-agents → Sonnet |
+| `balanced` *(default)* | Day-to-day work | Most agents → Sonnet; orchestrators → Opus; trivial helpers → Haiku |
+| `budget` | Exploration, low-stakes prototyping, cost-sensitive | Most agents → Haiku; only orchestrators → Sonnet |
+| `inherit` | Use whatever model the calling Claude Code session is on | All agents → session model |
+
+## Resolution order
+
+When a workflow spawns an agent:
+
+1. **Per-agent override** — if the agent's `.md` frontmatter has `model: <name>`, use that.
+2. **Profile mapping** — look up the agent role (strategic / technical / tactical / quality) in the active profile's table.
+3. **Project profile** — read `model_profile` from `.rihal/config.yaml`.
+4. **Global profile** — fall back to `~/.rihal-code/defaults.json` if the project doesn't specify.
+5. **Hard default** — `balanced`.
+
+## Model names referenced
+
+- **Claude Opus 4.7** (`claude-opus-4-7`) — strongest reasoning. Use for orchestration, council moderation, hard architecture calls.
+- **Claude Sonnet 4.6** (`claude-sonnet-4-6`) — balanced. Default for most agents.
+- **Claude Haiku 4.5** (`claude-haiku-4-5-20251001`) — fast + cheap. Use for tactical helpers (file walkers, simple transforms).
+
+When using the Anthropic API directly, defaults to the latest available model in each tier.
+
+## Override at invocation
+
+Per-invocation override:
+
+```bash
+RIHAL_MODEL_PROFILE=quality /rihal:execute-phase 04
+```
+
+Survives the session, doesn't persist to config.
+
+## Why profiles exist
+
+Cost vs quality is a real tradeoff. A retrospective doesn't need Opus. A council on a strategic decision shouldn't run on Haiku. Letting users pick a profile per-project means they don't have to reason about model selection per-agent.

package/rihal/references/phase-argument-parsing.md

@@ -1,11 +1,35 @@
 # Phase Argument Parsing
 
-Workflows accept a phase argument in two forms:
+Workflows that take a phase argument (`/rihal:plan 04`, `/rihal:execute-phase 999.5`, `/rihal:research-phase 12`) all use the same parsing rules.
 
-- **Numeric**: `01`, `2`, `02.1` — resolved via
-  `node .rihal/bin/rihal-tools.cjs init phase-op "$ARG"` to the matching
-  phase directory under `.planning/phases/`.
-- **Path**: a direct `.planning/phases/<slug>/PLAN.md` path — used as-is.
+## Accepted forms
 
-If the resolver returns `phase_found: false`, workflows must STOP with a
-"phase not found" message rather than fabricating a target.
+| Input | Resolves to | Notes |
+|-------|-------------|-------|
+| `04` | Phase 04 | Zero-padded NN |
+| `4` | Phase 04 | Auto-pads |
+| `999.5` | Decimal parking-lot phase 999.5 | See `docs/parking-lot-convention.md` |
+| `04.1` | Sub-phase 04.1 | Inserted-phase / urgent work |
+| `current` | The phase currently in `state.current_phase` | Useful when looping |
+| `next` | The next planned phase after current | Looks at ROADMAP.md ordering |
+| (empty) | Same as `current` if state has one; else error | Most workflows refuse empty |
+
+## Resolution
+
+1. Strip whitespace.
+2. Match against the patterns above (regex per row).
+3. Look up the resolved number in `state.phases[]`.
+4. If not found, fall back to looking on disk under `.planning/phases/<NN>-*/`.
+5. If neither, exit non-zero with: `Phase X not found. Run /rihal:status to list known phases.`
+
+## Strict vs lenient
+
+Workflows pass `--strict` if a missing phase should hard-fail rather than offering to create. By default, planning workflows ask "Phase X doesn't exist — create it now?" before erroring. Execution workflows hard-fail because executing a phase that doesn't exist is always a bug.
+
+## Error messages
+
+Always include the resolved (or attempted-resolve) value in the error. Never just say "phase not found" — say "Phase 12 not found in state.json (3 phases registered: 04, 05, 999.5)".
+
+## Multi-phase invocations
+
+Some workflows accept `04..06` to operate on a range, or `04 05 06` as space-separated. Each gets parsed by the rules above; the workflow operates on the resolved set in roadmap order.

package/rihal/references/revision-loop.md

@@ -1,11 +1,38 @@
-# Plan Revision Loop
+# Revision Loop
 
-When `workflow.plan_checker` is enabled (`/rihal-settings`), `/rihal-plan`
-runs the rihal-sprint-checker after the planner. Findings drive a bounded
-revision loop:
+When a plan is reviewed (by `rihal-plan-checker`, by a council, or by the user) and the verdict is "needs changes", the planner must run the revision loop — not silently accept the feedback and move on.
 
-1. Planner produces PLAN.md.
-2. Plan-checker scores against goal-backward criteria.
-3. If BLOCK / FLAG: planner revises with the findings as added input.
-4. Up to 2 revision rounds. After that, surface to user for manual
-   confirmation rather than loop indefinitely.
+## The loop
+
+1. **Receive feedback.** Capture every reviewer concern as a structured list:
+   - Source (which reviewer / agent / user)
+   - Concern (one-sentence summary)
+   - Suggested change (if any)
+   - Severity (blocker / warning / suggestion)
+
+2. **Triage.** For each concern, classify:
+   - **Accept** — change the plan as suggested.
+   - **Counter** — disagree, document why, keep original plan.
+   - **Defer** — out of scope for this phase; file as follow-up.
+
+3. **Apply.** Make the accepted changes to PLAN.md. Mark the diff in a "Revision N" section so reviewers can see what changed.
+
+4. **Re-circulate.** Send the revised plan back to the reviewer that surfaced the blocker. If a council reviewed, send to the same panel.
+
+5. **Iterate or proceed.**
+   - All blockers resolved → proceed to execute.
+   - Any blocker still standing → either escalate (to user) or stop the phase.
+
+## Loop bound
+
+Three revisions is the soft cap. If a plan needs four revisions, the underlying disagreement isn't about the plan — it's about scope, requirements, or strategy. Halt the loop, run `/rihal:discuss-phase` or `/rihal:council` to resolve the upstream disagreement, then start a fresh plan.
+
+## What never happens
+
+- Silent acceptance. If a concern is rejected ("counter"), it's documented with a reason in the PLAN.md revision history.
+- Blanket revisions. Each round addresses specific concerns from specific reviewers. Don't bundle "various improvements" into a single revision.
+- Skipping the loop because the planner thinks they know better. The loop exists because reviewers catch what planners miss.
+
+## Output of the loop
+
+A PLAN.md with a "Revision history" section showing each round, what changed, and who signed off. This becomes the audit trail when the phase ships and someone asks "why did we build it this way?"

package/rihal/references/universal-anti-patterns.md

@@ -1,15 +1,59 @@
-# Universal Anti-Patterns (Discuss-Phase)
+# Universal Anti-Patterns
 
-Common failure modes the discuss workflow checks for:
+Patterns that show up across every Rihal project. When a planning workflow surfaces these, halt and discuss before proceeding — they're cheap to fix during planning, expensive to fix after execution.
 
-- **Solution-first framing**: jumping to implementation before constraints
-  are explicit.
-- **Hidden binary choice**: presenting a "decision" that has only one
-  viable option.
-- **Unowned action**: a "we should X" with no owner or deadline.
-- **Sunk-cost continuation**: defending an existing plan instead of
-  evaluating fresh evidence.
-- **Scope inflation**: bundling new work into the current decision.
+## Scope anti-patterns
 
-Discuss-phase flags any of these and asks for explicit framing before
-proceeding.
+### "While we're at it…"
+Phase plan picks up scope adjacent to the actual goal. Symptom: phase description starts with the real goal but acceptance criteria reference 3 unrelated files. Fix: spin the side-scope into its own phase, even if it's a 1-day phase. Linear roadmaps are easier to verify than tangled ones.
+
+### Implicit prerequisites
+Phase assumes another phase has shipped without declaring the dependency. Symptom: plan refers to a file or table that doesn't exist yet. Fix: surface the dependency in the phase's `Depends on` line in ROADMAP.md.
+
+### Vague acceptance
+Acceptance criterion is "users can do X" with no measurable threshold. Fix: make every acceptance criterion observable from outside the system — a CLI command, an API response, a log line, a UI assertion.
+
+## Estimation anti-patterns
+
+### Round-number capacity
+Sprint commits to "30 points this week" because that's what last week was. No data-backed velocity. Fix: use 80% of the trailing 3-sprint average, never a round number.
+
+### Hidden multitasking
+Phase plan assumes the dev works on it full-time when in reality they're also on-call, in interviews, and at standups. Fix: explicit `effective_dev_hours` field in sprint capacity.
+
+## Decision anti-patterns
+
+### Reversible vs irreversible confusion
+Treating reversible decisions (CSS framework choice) like irreversible ones (database engine), and vice versa. Fix: tag every recorded decision with `reversibility: reversible | one-way | nuanced`.
+
+### Council asked, council ignored
+Council session produces a clear recommendation, the team builds the rejected option anyway. Fix: if you reject a council recommendation, explicitly log the override in `state.decisions[]` with `override_council: <session-id>` so the disagreement is searchable later.
+
+## Implementation anti-patterns
+
+### Defensive code for impossible states
+Adding null checks, fallbacks, and validation for inputs that can never occur in this code path. Fix: trust internal contracts. Validate at system boundaries (user input, network, FS), not internally.
+
+### "Just in case" abstractions
+Building a generic helper because someday three callers might need it, when right now there's one. Fix: three concrete callers first, then extract.
+
+### Comments that explain what
+"// increment counter by 1" — the code says that. Fix: comments only for *why* (hidden constraint, surprising behaviour, workaround for specific bug, invariant that's not obvious from reading).
+
+### Silent failures
+`try { ... } catch { /* ignore */ }`. Fix: every catch block has either a logged warning, a metric increment, or a re-throw. Never bare empty catches.
+
+## Process anti-patterns
+
+### Half-merged migrations
+Old code path and new code path both running in production "for safety". Fix: complete migrations within one phase. Both paths existing forever doubles the maintenance burden.
+
+### Documentation that ages out silently
+README written once, never updated. Code drifts. README lies. Fix: documentation that references specific files / functions includes a sentinel marker; CI fails if the docs reference paths that no longer exist.
+
+### "We'll fix it in v2"
+Known broken behaviour that ships anyway because the deadline. Fix: the phase doesn't ship if known-broken behaviour reaches users. Cut the broken feature, don't ship it broken.
+
+---
+
+When a phase plan or sprint hits any of these patterns during discussion, halt. Surface it explicitly. Adjust before execution starts. The cost compounds.

package/rihal/skills/SKILLS_INDEX.md

@@ -1,8 +1,8 @@
 # Rihal Code — Skills Index
 
-All 58 skills in Rihal Code, organized by category: 17 agent skills, 26 action skills, 13 core skills, plus 2 shared modules.
+All 85 skills in Rihal Code, organized by category: 23 agent skills, 37 action skills, 25 core skills, plus 2 shared modules.
 
-## Agent Skills (17)
+## Agent Skills (23)
 
 Each agent has a persona, principles, and a capabilities table that lists which action skills it can invoke.
 
@@ -25,12 +25,18 @@ Each agent has a persona, principles, and a capabilities table that lists which
 | **Zayd** | زيد | Senior ML Engineer | `agents/zayd-ml/` |
 | **Raees** | رئيس | Orchestrator | `agents/raees-orchestrator/` |
 | **Majlis** | مجلس | Multi-Agent Council | `agents/majlis-council/` |
+| **Dalil** | دليل | Codebase Scout | `agents/dalil-scout/` |
+| **Cross-Platform Auditor** | — | Cross-Platform Auditor | `agents/rihal-cross-platform-auditor/` |
+| **Dep Auditor** | — | Dependency Health Auditor | `agents/rihal-dep-auditor/` |
+| **Deviation Analyzer** | — | Deviation Analyzer | `agents/rihal-deviation-analyzer/` |
+| **i18n Auditor** | — | i18n / L10n Auditor | `agents/rihal-i18n-auditor/` |
+| **Observability Auditor** | — | Observability Auditor | `agents/rihal-observability-auditor/` |
 
 Note: Hussain has two hats — **PM** (strategic product management) and **SM** (scrum master / sprint ops). Real teams often combine these.
 
 ---
 
-## Action Skills (26)
+## Action Skills (37)
 
 Invoked by agents via the capabilities table in their SKILL.md. Organized by SDLC phase.
 
@@ -57,7 +63,7 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 - `actions/3-solutioning/rihal-check-implementation-readiness` — verify PRD/UX/arch alignment
 - `actions/3-solutioning/rihal-generate-project-context` — generate project-context.md
 
-### 4 — Implementation (9)
+### 4 — Implementation (20)
 - `actions/4-implementation/rihal-dev-story` — execute a story (write tests + code)
 - `actions/4-implementation/rihal-code-review` — comprehensive code review
 - `actions/4-implementation/rihal-qa-generate-e2e-tests` — generate e2e test suite
@@ -67,10 +73,21 @@ Invoked by agents via the capabilities table in their SKILL.md. Organized by SDL
 - `actions/4-implementation/rihal-correct-course` — course-correction for off-track stories
 - `actions/4-implementation/rihal-scaffold-project` — scaffold new project from Rihal template
 - `actions/4-implementation/rihal-checkpoint-preview` — LLM-assisted human-in-the-loop review
+- `actions/4-implementation/rihal-browser-verify` — verify browser behaviour via Chrome DevTools MCP
+- `actions/4-implementation/rihal-ci` — CI/CD setup and quality gates
+- `actions/4-implementation/rihal-debug` — root-cause debugging via the scientific method
+- `actions/4-implementation/rihal-git-flow` — branching, commits, conflicts, parallel work
+- `actions/4-implementation/rihal-harden` — security hardening checklist for SaaS apps
+- `actions/4-implementation/rihal-incremental` — ship code in small, atomic, verifiable steps
+- `actions/4-implementation/rihal-migrate` — move from MVP to production-grade infrastructure
+- `actions/4-implementation/rihal-perf` — performance optimisation (LCP / TBT / CLS / hydration)
+- `actions/4-implementation/rihal-prove-it` — test-first development
+- `actions/4-implementation/rihal-source-truth` — cite official docs before writing framework code
+- `actions/4-implementation/rihal-trim` — code simplification
 
 ---
 
-## Core Skills (13)
+## Core Skills (25)
 
 Shared utilities used across agents and workflows.
 
@@ -87,6 +104,18 @@ Shared utilities used across agents and workflows.
 - `core/rihal-review-adversarial-general` — adversarial review for robustness
 - `core/rihal-review-edge-case-hunter` — edge case hunting and boundary testing
 - `core/rihal-party-mode` — multi-agent collaboration mode
+- `core/rihal-auth-audit` — audit Keycloak ↔ AD sync, JWT validation, tenant isolation
+- `core/rihal-client-gate` — client requirement freeze gates and async-comm patterns
+- `core/rihal-deploy-unify` — detect and unify multiple deployment paths
+- `core/rihal-incident-record` — generate a change record + post-mortem
+- `core/rihal-memory-init` — bootstrap the Memory Bank for a project
+- `core/rihal-memory-update` — surgical update of specific Memory Bank files
+- `core/rihal-memory-audit` — audit the Memory Bank for stale entries and contradictions
+- `core/rihal-memory-distill` — regenerate token-optimised Memory Bank distillates
+- `core/rihal-mvp-graduate` — move an MVP to production-grade infrastructure incrementally
+- `core/rihal-ocr-consistency` — OCR pipeline determinism + ground-truth validation
+- `core/rihal-rebrand` — stack-wide rebranding migration
+- `core/rihal-theme-system` — audit a frontend's design tokens before launch
 
 ---
 

package/rihal/skills/actions/1-analysis/research/rihal-domain-research/SKILL.md

@@ -15,6 +15,7 @@ triggers:
   - "help
   me understand X industry"
   - "domain research for"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/1-analysis/research/rihal-market-research/SKILL.md

@@ -14,6 +14,7 @@ triggers:
   - "size the market"
   - "competitor scan"
   - "analyze the market for X"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/1-analysis/research/rihal-technical-research/SKILL.md

@@ -17,6 +17,7 @@ triggers:
   - "what stack for"
   - "technical
   feasibility for"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/1-analysis/rihal-document-project/SKILL.md

@@ -14,6 +14,7 @@ triggers:
   existing code"
   - "brownfield analysis"
   - "create LLM-friendly docs"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/1-analysis/rihal-prfaq/SKILL.md

@@ -9,6 +9,7 @@ triggers:
   - "create a prfaq"
   - "product concept challenge"
   - "forge a product idea"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/1-analysis/rihal-product-brief/SKILL.md

@@ -14,6 +14,7 @@ triggers:
   - "draft a brief for"
   - "product briefing"
   - "create the brief"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/SKILL.md

@@ -25,6 +25,7 @@ triggers:
   - "قسّم المتطلبات"
   - "ابني القائمة"
   - "تحليل وثيقة المتطلبات"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-create-epics-and-stories/workflow.md

@@ -4,6 +4,18 @@
 
 **Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
 
+## State-sync rule (NO EXCEPTIONS)
+
+After this workflow writes any `.planning/` artifact (ROADMAP.md, epics.md, sprint-*.md, SUMMARY.md, etc.) or updates phase/story status:
+
+```bash
+node .rihal/bin/rihal-tools.cjs state sync --from-disk
+```
+
+This keeps `.rihal/state.json` in sync with disk — `/rihal:progress`, `/rihal:status`, and `/rihal:execute` all read state.json. Skipping the sync silently drifts them. See `../../_shared/state-sync-rule.md`.
+
+---
+
 ---
 
 ## WORKFLOW ARCHITECTURE

package/rihal/skills/actions/2-plan/rihal-create-milestone/SKILL.md

@@ -17,6 +17,7 @@ triggers:
   - "break this project into
   milestones"
   - "roadmap for this product"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-create-prd/SKILL.md

@@ -27,6 +27,7 @@ triggers:
   - "وثيقة المتطلبات"
   - "ابدأ PRD"
   - "صمم المتطلبات"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-create-story/SKILL.md

@@ -25,6 +25,7 @@ triggers:
   - "حضّر القصة"
   - "القصة التالية"
   - "جهّز القصة للتنفيذ"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-create-ux-design/SKILL.md

@@ -15,6 +15,7 @@ triggers:
   - "UX plan"
   - "design this screen"
   - "create the design for"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-edit-prd/SKILL.md

@@ -14,6 +14,7 @@ triggers:
   - "add a section to the PRD"
   - "revise requirements"
   - "change the scope in the PRD"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-frontend-design/SKILL.md

@@ -26,6 +26,7 @@ triggers:
   - "editorial"
   - "maximalist"
 license: Adapted from Anthropic's frontend-design skill
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/2-plan/rihal-validate-prd/SKILL.md

@@ -14,6 +14,7 @@ triggers:
   - "PRD quality
   check"
   - "audit the PRD"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/3-solutioning/rihal-check-implementation-readiness/SKILL.md

@@ -15,6 +15,7 @@ triggers:
   - "readiness check"
   - "IR check"
   - "can we start building"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/3-solutioning/rihal-create-architecture/SKILL.md

@@ -18,6 +18,7 @@ triggers:
   - "lock this technical decision"
   - "record the
   decision to use X"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/3-solutioning/rihal-generate-project-context/SKILL.md

@@ -16,6 +16,7 @@ triggers:
   - "setup AI context"
   - "create
   project-context.md"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/SKILL.md

@@ -9,6 +9,7 @@ triggers:
   - "review before checkpoint"
   - "checkpoint review session"
   - "preview changes before approval"
+user-invocable: true
 ---
 
 ## Overview

package/rihal/skills/actions/4-implementation/rihal-code-review/SKILL.md

@@ -27,6 +27,7 @@ triggers:
   - "افحص الكود"
   - "تدقيق الكود"
   - "جودة الكود"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/4-implementation/rihal-correct-course/SKILL.md

@@ -16,6 +16,7 @@ triggers:
   - "handle scope
   change"
   - "change story mid-way"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md
 

package/rihal/skills/actions/4-implementation/rihal-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rihal-debug
-description: Root-cause debugging via the scientific method. Enforces investigate-before-fix, structured hypothesis iteration, multi-component evidence gathering, and architectural escalation after 3 failed fixes.
+description: Scientific-method debugging: investigate first, test hypotheses, escalate at 3 failures.
 triggers:
   # English
   - "debug this"
@@ -31,7 +31,6 @@ user-invocable: false
 ---
 @.rihal/references/karpathy-guidelines.md
 
-
 ## The Iron Law
 
 ```
@@ -45,7 +44,6 @@ If you have not completed Phase 1, you cannot propose a fix. "It seems to work"
 Debugging is investigation, not pattern-matching. Each iteration narrows the problem space — never widens it. The skill enforces a written hypothesis, an experiment that distinguishes "yes" from "no", and a captured observation. Random fixes are not allowed — the bug must be understood before the fix is written.
 
 ## Workflow
-
 ## Phase 1 — Root Cause Investigation
 
 **BEFORE attempting ANY fix:**
@@ -137,7 +135,6 @@ If the project has Sentry (`@sentry/*` in `package.json` or `sentry-sdk` in Pyth
 - Read breadcrumbs for the chain of events leading to the error
 - Check "first seen / last seen" — recurring or one-off matters
 - Cross-reference with deployment timestamps to identify regressions
-
 ## Red Flags — STOP and return to Phase 1
 
 If you catch yourself thinking any of these:
@@ -153,17 +150,6 @@ If you catch yourself thinking any of these:
 
 **ALL of these mean: STOP. Return to Phase 1.**
 
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Issue is simple, don't need process" | Simple bugs have root causes too. Process is fast for simple bugs. |
-| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
-| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
-| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
-| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
-| "One more fix attempt" (after 2+) | 3+ failures = architectural problem. Escalate, don't fix again. |
-
 ## Output Format
 
 ```
@@ -209,5 +195,5 @@ Do NOT include: "tried X and it seems to work" · speculative "maybe it's cachin
 
 ## Memory Bank Hooks
 
-- **Reads:** `.rihal/memory/incidents/known-issues.md` (prior debugging context), `.rihal/memory/project/stack.md` (Sentry presence, observability tools)
-- **Writes:** append root cause to `.rihal/memory/incidents/post-mortems/YYYYMMDD-<slug>.md` when resolved; remove from `known-issues.md` once fix is verified in production
+- **Reads:** `known-issues.md`, `stack.md`
+- **Writes:** append to `post-mortems/YYYYMMDD-<slug>.md`; remove from `known-issues.md` once fixed in production

package/rihal/skills/actions/4-implementation/rihal-dev-story/SKILL.md

@@ -15,6 +15,7 @@ triggers:
   - "run
   dev-story on"
   - "implement .rihal/phases/{phase}/stories/{file}"
+user-invocable: true
 ---
 @.rihal/references/karpathy-guidelines.md