@hanzlaa/rcode 2.8.0 → 3.2.0

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

@@ -1,19 +1,16 @@
 ---
 name: rihal-frontend-design
 description: >
-  Create distinctive, production-grade frontend interfaces with a
-  committed aesthetic direction — typography, color, motion, spatial
-  composition, backgrounds, and visual details that avoid generic
-  "AI slop" look. Activates when the user says "design this UI",
-  "build a beautiful frontend", "distinctive design", "creative UI",
-  "unforgettable interface", "award-winning design", "not generic",
-  "bold aesthetic", "brutalist", "editorial", "maximalist",
-  "minimalist luxury", "design a landing page", "standout hero
-  section", "make this look amazing", or "frontend design". Works
-  hand-in-hand with rihal-clone-website (for copying existing sites)
-  and rihal-agent-zahra (branding expert) for brand alignment. Do
-  NOT use for: cloning existing sites (use rihal-clone-website
-  instead), pure backend work, or documentation.
+  Create distinctive, production-grade frontend interfaces with a committed
+  aesthetic direction — typography, colour, motion, spatial composition,
+  backgrounds, visual details — that avoid generic "AI slop". Activates when
+  the user says "design this UI", "build a beautiful frontend", "distinctive
+  design", "creative UI", "unforgettable interface", "award-winning design",
+  "not generic", "bold aesthetic", "brutalist", "editorial", "maximalist",
+  "minimalist luxury", "design a landing page", "standout hero section",
+  "make this look amazing", or "frontend design". Pairs with rihal-clone-website
+  (for copying) and rihal-agent-zahra (branding). Do NOT use for: cloning
+  existing sites (use rihal-clone-website), pure backend, or documentation.
 triggers:
   - "AI slop"
   - "design this UI"
@@ -30,153 +27,66 @@ triggers:
 license: Adapted from Anthropic's frontend-design skill
 ---
 
-# Rihal Frontend Design
-
 ## Overview
 
-This skill guides the creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. It implements real working code with exceptional attention to aesthetic details and creative choices. The aim is interfaces that someone will actually remember.
-
-This is different from `rihal-clone-website`, which replicates an existing site pixel-for-pixel. This skill creates *original* design. It pairs naturally with Zahra (rihal-agent-zahra), Rihal's branding expert, who owns brand identity and ensures new UIs stay on-brand.
-
-## Design Thinking
-
-Before writing any code, understand the context and commit to a BOLD aesthetic direction:
-
-- **Purpose:** What problem does this interface solve? Who uses it?
-- **Tone:** Pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, Omani-modern (deserts, turquoise, gold, geometric Islamic patterns). These are inspiration — design one that is true to the intended direction.
-- **Constraints:** Technical requirements (framework, performance, accessibility, Arabic RTL support for Rihal work).
-- **Differentiation:** What makes this UNFORGETTABLE? What's the one thing someone will remember?
-
-**CRITICAL:** Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
-
-Then implement working code (HTML/CSS/JS, React, Vue, Next.js App Router) that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
-- **Bilingual-ready for Rihal work:** Arabic RTL from the start, not an afterthought
-
-## Frontend Aesthetics Guidelines
-
-### Typography
-Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive, characterful choices that elevate the frontend's aesthetics. Pair a distinctive display font with a refined body font.
-
-For Rihal/Omani work, consider Arabic-Latin font pairs that work together:
-- Latin: PP Neue Montreal, IBM Plex, Söhne, Editorial New, GT Sectra, Tiempos, Recoleta
-- Arabic: IBM Plex Arabic, Adelle Sans Arabic, Readex Pro, Tajawal, Cairo, El Messiri, Noto Naskh Arabic
-
-### Color & Theme
-Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-
-Rihal's official palette (when branding alignment matters): Rihal blue `#1e3a8a`, gold `#f59e0b`. For original work, use these as optional anchors but don't force them.
+Builds **original** frontend interfaces with a committed aesthetic direction. Goal: interfaces someone actually remembers. Different from `rihal-clone-website` (which replicates existing sites pixel-for-pixel). Pairs with `rihal-agent-zahra` for brand alignment. Detailed aesthetic guidelines, type pair recommendations, "what to avoid" list, and Rihal-specific RTL guidance live in [`references.md`](references.md).
 
-### Motion
-Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML; use Motion library for React when available. Focus on high-impact moments: **one well-orchestrated page load with staggered reveals** (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+## Design Thinking — commit before coding
 
-### Spatial Composition
-Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density — pick your philosophy.
+Before writing any code, lock these:
 
-### Backgrounds & Visual Details
-Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic: gradient meshes, noise textures, geometric patterns (Islamic geometric art fits well for Omani work), layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.
+- **Purpose** — what problem does this UI solve? Who uses it?
+- **Tone** — pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic, luxury-refined, playful, editorial, brutalist, art-deco, soft pastel, industrial, Omani-modern. **Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.**
+- **Constraints** — framework, performance, accessibility, Arabic RTL support.
+- **Differentiation** — what's the one thing someone will remember?
 
-## What To Avoid
-
-**NEVER use generic AI-generated aesthetics:**
-- Overused font families: Inter, Roboto, Arial, system fonts, Space Grotesk (extremely overused — never use it as default)
-- Clichéd color schemes: purple gradients on white backgrounds, "AI blue" default themes
-- Predictable layouts: hero + three-column features + CTA
-- Cookie-cutter Tailwind defaults without customization
-- Cookie-cutter shadcn/ui without restyling
-- Centered stacks with identical spacing
-- Emoji as primary visual element
-
-**Interpret creatively.** Make unexpected choices that feel genuinely designed for the context. No two designs should be the same. Vary between light and dark themes, different fonts, different aesthetics. **NEVER converge on common choices across generations.**
-
-## Implementation Philosophy
-
-**IMPORTANT:** Match implementation complexity to the aesthetic vision:
-- Maximalist designs need elaborate code with extensive animations and effects
-- Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details
-- Elegance comes from executing the vision well, not from decorating a weak idea
-
-Claude is capable of extraordinary creative work. Don't hold back — show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
-
-## Rihal-Specific Guidelines
-
-When designing for Rihal work (government clients, enterprise dashboards, Arabic audiences):
-
-1. **RTL is foundational, not retrofitted.** Use logical CSS properties (`padding-inline-start` not `padding-left`) from day one.
-2. **Arabic typography needs different scale.** Arabic glyphs are visually denser; bump line-height +10%, let letter-spacing breathe.
-3. **Cultural context.** Islamic geometric patterns, Omani colors (desert sand, turquoise, gold, deep blue), bilingual parity — not token gestures.
-4. **Government dashboards** favor authoritative restraint over playful chaos. Enterprise dashboards can be more confident.
-5. **Never compromise on accessibility** for aesthetic impact. WCAG AA minimum, AAA where feasible.
+Then implement code that is production-grade, visually striking, cohesive, refined in detail, and bilingual-ready (RTL from day one for Rihal work).
 
 ## Workflow
 
-1. **Understand context** — ask about purpose, audience, technical constraints, brand alignment
-2. **Commit to a direction** — state the aesthetic in one sentence before writing code
-3. **Check brand alignment** — if Rihal branding matters, invoke Zahra (rihal-agent-zahra) for brand tokens
-4. **Select type pair** — display font + body font, with Arabic companion if bilingual
-5. **Define color system** — dominant + accents, not a rainbow
-6. **Design motion choreography** — what animates when, what's the hero moment
-7. **Implement with precision** — every detail refined, every pixel intentional
-8. **Verify at all viewports** — desktop, tablet, mobile, RTL version
-9. **Stress-test with content** — long names, empty states, error states, loading states
+1. **Understand context** — ask about purpose, audience, constraints, brand alignment.
+2. **Commit to a direction** — state the aesthetic in one sentence before writing code.
+3. **Check brand alignment** — if Rihal branding matters, invoke Zahra (`rihal-agent-zahra`) for brand tokens.
+4. **Select type pair** — display + body, with Arabic companion if bilingual.
+5. **Define colour system** — dominant + accents, not a rainbow.
+6. **Design motion choreography** — what animates when, what's the hero moment.
+7. **Implement with precision** — every detail refined, every pixel intentional.
+8. **Verify at all viewports** — desktop, tablet, mobile, RTL.
+9. **Stress-test content** — long names, empty states, error states, loading states.
 
 ## Output Format
 
-- Response: Markdown explanation + fenced code blocks (language-tagged)
+- Markdown explanation + fenced code blocks (language-tagged)
 - Start with a one-sentence aesthetic statement before any code
-- Show the complete file, not fragments
-- For React/Next.js: Server Components by default, Client Components only when needed
-- For Tailwind: use custom config extensions, not raw class spam
-- For CSS: use CSS variables for tokens
-- Do NOT include: Inter as the default font, generic purple/blue gradients, centered cookie-cutter layouts, or undifferentiated "looks fine" designs
-- Do NOT default to shadcn/ui without visible customization
-- Do NOT ship designs without specified type pair, color system, and motion direction
-
-## Examples
-
-### Happy Path: Original Landing Page
-**Input:** "Design a landing page for an Omani heritage tourism startup"
+- Show complete files, not fragments
+- React / Next.js: Server Components by default, Client Components only when needed
+- Tailwind: custom config extensions, not raw class spam
+- CSS: variables for tokens
 
-**Expected behavior:**
-1. State aesthetic: "Editorial-magazine tone with Islamic geometric motifs, warm desert palette, slow cinematic type reveals"
-2. Type pair: GT Sectra Display (Latin headline) + Tajawal (Arabic + Latin body)
-3. Color system: `#2C1810` (deep bronze), `#D4A574` (desert sand), `#0F3B3C` (turquoise oasis), `#F5EFE0` (parchment)
-4. Motion: hero h1 staggered per-word with ease-out, subtle parallax on geometric patterns
-5. Spatial: asymmetric grid, large editorial photography, generous margin-inline
-6. Arabic RTL version with mirrored layout and Arabic-aware line-height
-7. Complete working code (Next.js page + Tailwind config extension + CSS vars)
+Do NOT include: Inter or Space Grotesk as default fonts, generic purple/blue gradients, centred cookie-cutter layouts, "looks fine" designs, undifferentiated shadcn/ui. Do NOT ship without a specified type pair, colour system, and motion direction.
 
-### Happy Path: Dashboard
-**Input:** "Design a Ministry of Energy analytics dashboard"
+## Examples
 
-**Expected behavior:**
-1. Aesthetic: "Authoritative Omani-modern — deep navy authority, desert gold accents, IBM Plex for gravitas, zero playfulness"
-2. Type: IBM Plex Sans (Latin) + IBM Plex Arabic
-3. Color: Deep navy `#0B1A3A`, gold `#C8A05C`, neutral `#E8EAED`, danger `#B91C1C`
-4. Motion: Restrained — data appears on load with subtle fade, no decorative animations
-5. Spatial: dense grid, aligned tabular data, clear hierarchy
-6. Arabic RTL dashboard mirrored with Arabic numerals optional
-7. Accessibility: AAA contrast, keyboard navigation, screen reader labels
+**Happy path — original landing**
+"Design a landing page for an Omani heritage tourism startup" → aesthetic: "editorial-magazine with Islamic geometric motifs, warm desert palette, slow cinematic type reveals" → type pair GT Sectra Display + Tajawal → colours `#2C1810 / #D4A574 / #0F3B3C / #F5EFE0` → hero h1 staggered per-word → asymmetric grid → Arabic RTL mirrored → complete Next.js + Tailwind code.
 
-### Edge Case: Brand Conflict
-**Input:** "Build a playful colorful landing for a Rihal government client"
+**Happy path — dashboard**
+"Ministry of Energy analytics dashboard" → "authoritative Omani-modern, deep navy + desert gold, IBM Plex for gravitas, zero playfulness" → IBM Plex Sans + Arabic → restrained motion → dense grid → AAA contrast + keyboard navigation.
 
-**Expected behavior:** Flag the conflict. Respond: "Government clients expect authoritative restraint. 'Playful colorful' doesn't fit the Ministry audience. Options: (1) playful brand for a different audience, (2) confident editorial tone that's warmer without being childish. Which? I can invoke Zahra (rihal-agent-zahra) to verify brand fit."
+**Edge case — brand conflict**
+"Build a playful colourful landing for a Rihal government client" → flag the conflict. Government audiences expect restraint. Offer alternatives or invoke Zahra to verify brand fit.
 
-### Edge Case: Generic Request
-**Input:** "Design a landing page, modern and clean"
+**Edge case — generic request**
+"Design a landing page, modern and clean" — refuse. Ask the user to pick an extreme or describe a site they love.
 
-**Expected behavior:** Refuse generic. Ask: "'Modern and clean' is what everyone says and nothing memorable looks like. Pick an extreme: brutally minimal, editorial-magazine, luxury-refined, retro-futuristic, organic, brutalist. Or describe a site you love. Without a direction, I'd just build another forgettable landing page."
+**Negative — wrong skill**
+"Clone https://linear.app" → cloning is `rihal-clone-website`'s job, redirect.
 
-### Negative Test
-**Input:** "Clone https://linear.app"
+## Memory Bank Hooks
 
-**Expected behavior:** Stay silent. This is cloning, not original design. Redirect: "Cloning is `rihal-clone-website`'s job. I create original designs; cloning extracts existing ones."
+- **Reads:** `.rihal/memory/project/stack.md` (frontend framework), brand tokens from Zahra if available
+- **Writes:** the implemented frontend files; consider noting design system choices in `.rihal/memory/project/decisions.md`
 
-### Negative Test 2
-**Input:** "Write the API for this feature"
+## Detailed reference
 
-**Expected behavior:** Stay silent. Redirect: "Backend APIs belong to Yousef (rihal-agent-yousef). I do frontend design, not API contracts."
+See [`references.md`](references.md) for: typography pairings (Latin + Arabic), colour philosophy, motion principles, spatial composition rules, the "what to avoid" list, and Rihal-specific RTL + government-client guidelines.

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

@@ -0,0 +1,79 @@
+# Frontend Design — Detailed Reference
+
+Detailed aesthetic guidelines for [`SKILL.md`](SKILL.md).
+
+---
+
+## Typography
+
+Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive, characterful choices that elevate the frontend's aesthetics. Pair a distinctive display font with a refined body font.
+
+For Rihal / Omani work, consider Latin + Arabic pairs that work together:
+
+**Latin display & body:** PP Neue Montreal, IBM Plex, Söhne, Editorial New, GT Sectra, Tiempos, Recoleta.
+**Arabic companions:** IBM Plex Arabic, Adelle Sans Arabic, Readex Pro, Tajawal, Cairo, El Messiri, Noto Naskh Arabic.
+
+---
+
+## Colour & theme
+
+Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colours with sharp accents outperform timid, evenly-distributed palettes.
+
+Rihal's official palette (when brand alignment matters): Rihal blue `#1e3a8a`, gold `#f59e0b`. For original work, use these as optional anchors — don't force them.
+
+---
+
+## Motion
+
+Use animation for effects and micro-interactions. Prioritise CSS-only solutions for HTML; use Motion library for React when available. Focus on high-impact moments: **one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions.** Use scroll-triggering and hover states that surprise.
+
+---
+
+## Spatial composition
+
+Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density — pick a philosophy and execute it.
+
+---
+
+## Backgrounds & visual details
+
+Create atmosphere and depth instead of defaulting to solid colours. Add contextual effects and textures that match the aesthetic: gradient meshes, noise textures, geometric patterns (Islamic geometric art fits well for Omani work), layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.
+
+---
+
+## What to avoid
+
+Never use generic AI-generated aesthetics:
+
+- Overused fonts: Inter, Roboto, Arial, system fonts. **Space Grotesk is extremely overused — never use as default.**
+- Clichéd colour schemes: purple gradients on white, "AI blue" defaults.
+- Predictable layouts: hero + three-column features + CTA.
+- Cookie-cutter Tailwind defaults without customisation.
+- Cookie-cutter shadcn/ui without restyling.
+- Centred stacks with identical spacing.
+- Emoji as primary visual element.
+
+**Interpret creatively.** Make unexpected choices that feel genuinely designed for the context. No two designs should be the same. Vary between light and dark, fonts, aesthetics. **Never converge on common choices across generations.**
+
+---
+
+## Implementation philosophy
+
+Match implementation complexity to the aesthetic vision:
+- Maximalist designs need elaborate code with extensive animations and effects.
+- Minimalist or refined designs need restraint, precision, careful attention to spacing, typography, subtle details.
+- Elegance comes from executing the vision well, not from decorating a weak idea.
+
+Don't hold back — show what can be created when committing fully to a distinctive vision.
+
+---
+
+## Rihal-specific guidelines
+
+When designing for Rihal (government clients, enterprise dashboards, Arabic audiences):
+
+1. **RTL is foundational, not retrofitted.** Use logical CSS properties (`padding-inline-start`, not `padding-left`) from day one.
+2. **Arabic typography needs different scale.** Arabic glyphs are visually denser; bump line-height +10%, let letter-spacing breathe.
+3. **Cultural context.** Islamic geometric patterns; Omani colours (desert sand, turquoise, gold, deep blue); bilingual parity — not token gestures.
+4. **Government dashboards** favour authoritative restraint over playful chaos. Enterprise dashboards can be more confident.
+5. **Never compromise accessibility** for aesthetic impact. WCAG AA minimum, AAA where feasible.

package/rihal/skills/actions/4-implementation/rihal-browser-verify/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: rihal-browser-verify
+description: Use Chrome DevTools MCP to verify browser behaviour — DOM state, console errors, network requests, performance traces, screenshot diffs. Use when implementing or debugging any browser-runtime feature, especially Three.js scenes, scroll-driven UI, or frontend perf concerns. Closes the gap between "the build passes" and "the user actually sees what we intended".
+triggers:
+  - "verify in browser"
+  - "check the dom"
+  - "browser test"
+  - "dev tools mcp"
+  - "screenshot diff"
+  - "console errors"
+  - "network trace"
+  - "browser smoke test"
+user-invocable: true
+---
+
+## Overview
+
+A passing build doesn't mean a working UI. This skill drives Chrome via the DevTools MCP server to inspect actual runtime: DOM nodes, console output, network requests, computed CSS, performance traces, and screenshots. Especially valuable for Three.js (where `getComputedStyle` lies and frame timing is the only truth), scroll-driven UI, and bisecting "works on dev, breaks on prod".
+
+## Pre-flight
+
+Chrome DevTools MCP must be available. If not, halt with: *"DevTools MCP not configured. Enable it before running this skill — without browser inspection we'd be guessing from HTML."*
+
+## Workflow
+
+1. **Identify the surface to verify.** A specific URL, route, or component path.
+2. **Choose verification mode:**
+   - **Static** — DOM + computed CSS + screenshot (default; fast)
+   - **Dynamic** — record interactions; capture before/after states
+   - **Performance** — trace, FPS, paint flame chart (for Three.js, animations, smooth-scroll libs)
+   - **Network** — failed requests, slow waterfalls, missing resources
+3. **Boot the dev server** (or open the prod URL). Confirm it loads without console errors first.
+4. **Run the appropriate DevTools queries.** For DOM: `document.querySelector(...).getBoundingClientRect()` etc. For perf: start trace, exercise the surface, stop trace.
+5. **Diff against expectation.** Either a stored baseline screenshot or a verbal description from the user.
+6. **Report findings** with concrete evidence — pixel coordinates, console messages verbatim, network failures by URL, frame times in ms.
+
+## Output Format
+
+```
+Surface verified: <URL or route>
+Mode: <static | dynamic | performance | network>
+
+Findings:
+  ✓ <thing that passed>
+  ⚠ <warning, with evidence>
+  ✗ <failure, with evidence>
+
+Console output (filtered for errors/warnings):
+  <verbatim>
+
+Recommendation:
+  <next action — fix, defer, or accept>
+```
+
+Do NOT include: "looks fine to me" without inspection; subjective "the page seems slow" without a trace; fixes applied without re-verifying.
+
+## Examples
+
+**Happy path — Three.js perf** — "Hero scene drops to 20fps on entry" → record perf trace → identify long task in `setupGeometry()` → recommend deferring `geometry.computeVertexNormals()` to a Web Worker → verify trace post-fix shows steady 60fps.
+
+**Happy path — scroll-driven UI** — "Tabs switch on scroll but layout jumps" → static check shows `position: sticky` conflicts with `transform` on parent → fix; re-verify with screenshot diff.
+
+**Edge case — works on dev, breaks on prod** — Console shows "ChunkLoadError" only on prod. Network trace shows missing `/_next/static/chunks/...js` (404). Recommend: re-deploy or check CDN purge.
+
+**Negative — no DevTools MCP** — Halt. Without DevTools the skill is a guess; the user gets a clear error and a path to enable it.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/project/stack.md` (frontend layer detection)
+- **Writes:** append to `.rihal/memory/incidents/known-issues.md` if a browser-runtime bug is acknowledged but not fixed in this session

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

@@ -11,7 +11,7 @@ Checkpoint preview skill for Rihal Code.
 
 ## Do NOT use this skill for
 
-- **Automated code review without a human** — use `/rihal:karpathy-audit` or a code-reviewer agent directly.
+- **Automated code review without a human** — use `/rihal:code-review --karpathy` or a code-reviewer agent directly.
 - **Approving a deploy or merge** — this skill explains a change; it does not authorize git push, deploys, or PR merges.
 - **Bug investigation** from scratch — use `/rihal:debug` or the diagnose-issues workflow.
 - **Architecture review of an undelivered design** — this skill reviews delivered code/diffs, not specs.

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

@@ -0,0 +1,108 @@
+---
+name: rihal-ci
+description: CI/CD setup and quality gates for the rcode-default stack — GitHub Actions for Node test matrix, Helm charts for K8s deployment, Docker Compose for dev environments. Use when standing up CI for a new repo, adding a quality gate, debugging a flaky workflow, or migrating dev-compose to production Helm. Opinionated about zero-runtime-dep invariants and pre-merge gates.
+triggers:
+  - "set up ci"
+  - "github actions"
+  - "ci pipeline"
+  - "quality gate"
+  - "helm chart"
+  - "docker compose"
+  - "k8s deploy"
+  - "release workflow"
+user-invocable: true
+---
+
+## Overview
+
+CI is the contract that keeps `main` green. This skill enforces a small, predictable set of gates rather than a sprawling pipeline. For deployment, the rcode-default path is: Docker Compose for dev → Helm chart for K8s production. The skill knows the common pitfalls (env drift, missing healthchecks, cold-start memory limits).
+
+## CI pre-merge gates (in order)
+
+1. **Lint / format.** Whatever the project uses (ESLint, Prettier, ruff). Auto-fixable issues block merge.
+2. **Type check.** `tsc --noEmit` for TS projects, `mypy --strict` for Python.
+3. **Test.** `node --test` / `pnpm test` / `pytest`. Across the supported runtime matrix (e.g. Node 18/20/22/24).
+4. **Build.** Whatever produces shippable artefacts. Fails-on-warnings.
+5. **Custom invariants.** rcode example: `zero-dep` job that asserts `package.json` has no runtime dependencies.
+
+If any gate fails, no merge. No `--no-verify`. Fix the underlying issue.
+
+## GitHub Actions template (Node project)
+
+```yaml
+name: test
+on:
+  push:    { branches: [main] }
+  pull_request: { branches: [main] }
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['18.x', '20.x', '22.x', '24.x']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '${{ matrix.node-version }}' }
+      - run: node --test
+```
+
+Reference the production rcode workflow at `.github/workflows/test.yml` for the full pattern (zero-dep invariant + syntax-check job).
+
+## Docker Compose dev environment
+
+- **Healthchecks on every service.** Postgres, Redis, the app — all of them. Without healthchecks `depends_on` is a lie.
+- **Volumes for source code only.** Don't volume-mount `node_modules`; use a named volume to avoid cross-host syncs.
+- **Single `.env.example`** in the repo. CI doesn't load it, but new contributors copy from it.
+- **One docker-compose.yml.** No "dev" / "prod" splits — production is Helm. Compose is for laptops only.
+
+## Helm chart conventions (K8s production)
+
+- **`values.yaml` documents every config knob.** No silent defaults.
+- **Liveness AND readiness probes.** Liveness is "process alive"; readiness is "ready to serve". Different thresholds.
+- **Resource limits.** Memory request = limit (no over-commit). CPU request realistic; limit forgiving.
+- **`PodDisruptionBudget`** for any deployment with `replicas > 1`.
+- **Secrets via External Secrets Operator** or sealed-secrets. Never plain `Secret` objects in git.
+
+## Workflow
+
+1. **Detect what's there.** Read `.github/workflows/`, `docker-compose.yml`, `helm/` (or wherever charts live).
+2. **Map to the gates above.** What's missing? What's redundant?
+3. **Add the smallest set of gates** that covers lint + types + tests + build + invariants.
+4. **Verify locally first.** Every gate should runnable on the contributor's laptop with `act` (for Actions) or directly.
+5. **Push, watch the run, fix.** Iterate until green on a real PR, not just locally.
+
+## Output Format
+
+```
+Detected CI: <list of existing workflows>
+Detected dev environment: <docker-compose | makefile | scripts>
+Detected production: <helm | terraform | none>
+
+Gates currently in place:
+  ✓ <gate>
+  ✗ missing: <gate>
+
+Recommendations:
+  1. <add or modify>
+  2. ...
+
+Next steps:
+  - <commit + PR>
+  - <verify run>
+```
+
+## Examples
+
+**Happy path — fresh repo** — No CI yet. Add `.github/workflows/test.yml` with the matrix template. Add `docker-compose.yml` with Postgres + app + healthchecks. Open a PR; verify CI runs green.
+
+**Edge case — flaky test in CI only** — Test passes locally, fails in CI 30% of the time. Bisect: is it a timeout? a race condition with the mock server? a CI-specific resource limit? Fix the root cause; don't add `retry: 3` as a workaround.
+
+**Negative — "just disable the failing check"** — Refuse. The check exists for a reason. Either fix what's broken or remove the check with a documented rationale.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/project/stack.md` (deploy target)
+- **Writes:** when CI gains a new gate, append to `.rihal/memory/project/decisions.md` with the rationale

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

@@ -0,0 +1,78 @@
+---
+name: rihal-debug
+description: Root-cause debugging via the scientific method. Use when a test fails, a build breaks, behaviour doesn't match expectations, or any "it's broken and I don't know why" moment. Forces hypothesis → experiment → observation → narrow → repeat — never guessing or shotgunning fixes. Default observability layer is Sentry; the skill knows how to read Sentry traces if available.
+triggers:
+  - "debug this"
+  - "why is this broken"
+  - "find the root cause"
+  - "investigate the bug"
+  - "what's wrong"
+  - "track this down"
+  - "narrow down the bug"
+  - "scientific method"
+user-invocable: true
+---
+
+## Overview
+
+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 that "happen to work" are not allowed — the bug must be understood.
+
+## Workflow
+
+1. **Reproduce the bug.** Write the exact steps. If you can't reproduce it, the first job is making it reproducible — anything else is guessing.
+2. **State the hypothesis.** "I think the bug is in <component>; specifically <mechanism>." One sentence, falsifiable.
+3. **Design the experiment.** What single test, log line, or dataflow change would distinguish a true hypothesis from a false one?
+4. **Run it. Capture the observation.** Console output verbatim, screenshot, stack trace, network response — whatever the experiment produced.
+5. **Update the hypothesis.** Either confirmed (now narrow to the next layer) or refuted (form a new hypothesis based on what was observed).
+6. **Stop conditions:** the bug is reproducible from a unit test (then hand to `rihal-prove-it`), OR the root cause is a known external constraint (e.g. third-party API behaviour) that you record in `incidents/known-issues.md`.
+7. **Never apply a fix without understanding why it works.** "It seems to fix it" is a red flag — keep investigating until the mechanism is clear.
+
+## Sentry / observability integration
+
+If the project has Sentry (`@sentry/*` in `package.json` or `sentry-sdk` in Python):
+
+- Quote the actual Sentry issue ID and stack trace in the hypothesis section
+- Look at breadcrumbs for the chain of events leading to the error
+- Check the issue's "first seen / last seen" — recurring or one-off matters
+- Cross-reference with deployment timestamps to identify regressions
+
+## Output Format
+
+```
+Reproduction:
+  <exact steps>
+  <observed vs expected>
+
+Iteration 1
+  Hypothesis: <falsifiable claim>
+  Experiment: <what we did>
+  Observation: <verbatim output>
+  Outcome: confirmed | refuted | partial
+
+Iteration N
+  ...
+
+Root cause:
+  <one paragraph explanation of the actual mechanism>
+
+Fix scope:
+  <minimum change that fixes the cause, not the symptom>
+
+Regression test:
+  <hand off to rihal-prove-it for the test that locks the fix in>
+```
+
+Do NOT include: "tried X and it seems to work"; speculative "maybe it's caching"; broad refactors disguised as bug fixes.
+
+## Examples
+
+**Happy path** — "Login fails for Arabic usernames" → reproduce: POST `/login` with `محمد` returns 500 → hypothesis: encoding boundary in URL parsing → experiment: add hex-dump log of the raw request → observation: bytes are UTF-8 but the Postgres driver re-encodes as Latin-1 → root cause: client_encoding mismatch → fix: pin client_encoding=utf8 → regression test asserts non-ASCII login returns 200.
+
+**Edge case — flaky test** — Test passes locally, fails in CI 30% of the time → hypothesis: race condition → experiment: run with `--runInBand` → observation: still flaky → next hypothesis: filesystem timing → experiment: await fs.stat after write → confirmed → fix.
+
+**Negative — shotgun fix** — "I added a try/catch around the whole function and now it doesn't crash". Refuse. The exception is now silently swallowed; the bug still exists. Restore the throw and form a real hypothesis.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/incidents/known-issues.md` (so prior debugging context is loaded), `.rihal/memory/project/stack.md` (Sentry presence)
+- **Writes:** append the root cause to `.rihal/memory/incidents/post-mortems/YYYYMMDD-<slug>.md` when an incident is resolved; remove the entry from `known-issues.md` once the fix is verified in production