@hanzlaa/rcode 3.6.15 → 4.0.0

package/rcode/skills/core/rcode-editorial-review-structure/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: rcode-editorial-review-structure
+description: Structural editor that proposes cuts, reorganization, and consolidation while preserving.
+triggers:
+  - "editorial review structure"
+  - "structural review"
+  - "tighten this doc"
+  - "review document structure"
+  - "cut this doc down"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Structural editor focused on high-value density. Reviews a document's organisation and proposes substantive changes — cut, merge, move, condense — without altering content. Brevity equals clarity; every section must justify its existence. Outputs prioritised recommendations the user accepts or rejects. **Content is sacrosanct** — never challenge ideas, only optimise how they are organised. Detailed principles, structure models, and the recommendation schema live in [`references.md`](references.md).
+
+## Inputs
+
+- `content` (required) — the document
+- `style_guide` (optional) — overrides all generic principles in this skill except "content is sacrosanct"
+- `purpose` (optional) — e.g. "quickstart tutorial", "API reference"
+- `target_audience` (optional) — e.g. "new users", "decision makers"
+- `reader_type` (optional, default `humans`) — `humans` preserves comprehension aids; `llm` optimises for precision and density
+- `length_target` (optional) — e.g. "30% shorter", "no limit"
+
+## Workflow
+
+1. **Validate input.** HALT if content is fewer than 3 words or `reader_type` is invalid. Note current word and section counts.
+2. **Understand purpose.** Use provided `purpose` and `target_audience` or infer them. Pick the structure model that fits (Tutorial / Reference / Explanation / Prompt / Pyramid — see references).
+3. **Structural analysis.** If `style_guide` provided, consult it first. Map every section's word count. Test against the model's rules (e.g. "does the recommendation come first?" for Pyramid). Identify cuts, merges, moves, splits, true redundancies, scope violations, buried critical information.
+4. **Flow analysis.** Does the sequence match how readers use the doc? Look for premature detail, missing scaffolding, FAQs that should be inline, appendices that should be cut, summaries that repeat the body verbatim.
+5. **Generate recommendations.** Categorise each: `CUT`, `MERGE`, `MOVE`, `CONDENSE`, `QUESTION`, `PRESERVE`. One-sentence rationale, estimated word impact. Flag cuts that may hurt comprehension when `reader_type=humans`.
+6. **Output.** Document summary + prioritised recommendations + total estimated reduction. If nothing to fix: "No substantive changes recommended — document structure is sound." (valid completion, not an error.)
+
+## Output Format
+
+```markdown
+## Document Summary
+- Purpose: ...
+- Audience: ...
+- Reader type: humans | llm
+- Structure model: tutorial | reference | explanation | prompt | pyramid
+- Current length: X words across Y sections
+
+## Recommendations
+### 1. [CUT|MERGE|MOVE|CONDENSE|QUESTION|PRESERVE] — Section name
+Rationale: ...
+Impact: ~X words
+Comprehension note: (if applicable)
+
+## Summary
+- Total recommendations: N
+- Estimated reduction: X words (Y%)
+- Meets length target: Yes | No | no target specified
+- Comprehension trade-offs: ...
+```
+
+## Examples
+
+**Happy path** — `structural review of this tutorial` → 6 recommendations (2 CUT, 1 MERGE, 2 MOVE, 1 CONDENSE) → ~30% reduction estimated.
+
+**Edge case — already tight** — Output: "No substantive changes recommended — document structure is sound."
+
+**Negative — wrong skill** — `fix the typos in this doc` is prose, not structure. Route to `rcode-editorial-review-prose`.
+
+## Memory Bank Hooks
+
+- **Reads:** the document passed in; `style_guide` if referenced
+- **Writes:** nothing — produces a recommendations report only
+
+## Detailed reference
+
+See [`references.md`](references.md) for: the full principle list, human-reader vs LLM-reader principles, the five structure models with applicability rules, and HALT conditions.

package/rcode/skills/core/rcode-editorial-review-structure/references.md

@@ -0,0 +1,110 @@
+# Editorial Review (Structure) — Detailed Reference
+
+Detailed principles and models for [`SKILL.md`](SKILL.md).
+
+---
+
+## Core principles
+
+- **Comprehension through calibration** — minimum words needed to maintain understanding.
+- **Front-load value** — critical information first; nice-to-know last (or cut).
+- **One source of truth** — if information appears identically twice, consolidate.
+- **Scope discipline** — content that belongs in a different document should be cut or linked.
+- **Propose, don't execute** — output recommendations; the user decides what to accept.
+- **Content is sacrosanct** — never challenge ideas, only optimise how they're organised.
+
+---
+
+## Human-reader principles (preserve unless clearly wasteful)
+
+When `reader_type=humans`:
+
+- **Visual aids** — diagrams, images, flowcharts anchor understanding.
+- **Expectation-setting** — "What you'll learn" helps readers confirm fit.
+- **Reader's journey** — organise biologically (linear progression), not logically (database).
+- **Mental models** — overview before details prevents cognitive overload.
+- **Warmth** — encouraging tone reduces anxiety for new users.
+- **Whitespace** — admonitions and callouts provide visual breathing room.
+- **Summaries** — recaps reinforce; they're not redundancy.
+- **Examples** — concrete illustrations make abstract concepts accessible.
+- **Engagement** — transitions and variety maintain attention; they're functional, not "fluff".
+
+---
+
+## LLM-reader principles (when `reader_type=llm`)
+
+Optimise for precision and unambiguity:
+
+- **Dependency-first** — define concepts before usage to minimise hallucination risk.
+- **Cut emotional language**, encouragement, orientation sections.
+- **Reference known standards** ("conventional commits", "Google style guide") — leverage training. But still provide examples to ground specific expectations.
+- **Consistent terminology** — same word for same concept throughout.
+- **Eliminate hedging** — no "might", "could", "generally". Direct statements.
+- **Prefer structured formats** — tables, lists, YAML — over prose.
+- **Unambiguous references** — no unclear antecedents like "it", "this", "the above".
+
+LLM-targeted documents may be longer than human ones in some areas (more explicit) and shorter in others (no warmth).
+
+---
+
+## Structure models
+
+Pick the one matching the document's purpose.
+
+### Tutorial / Guide (Linear)
+**For:** tutorials, how-to articles, walkthroughs.
+- Prerequisites: setup must precede action.
+- Sequence: strict chronological or logical dependency order.
+- Goal-oriented: clear "Definition of Done" at the end.
+
+### Reference / Database
+**For:** API docs, glossaries, configuration references, cheat sheets.
+- Random access — no narrative flow required; users jump to specific items.
+- MECE — topics are Mutually Exclusive and Collectively Exhaustive.
+- Consistent schema — every item follows identical structure (Signature → Params → Returns).
+
+### Explanation (Conceptual)
+**For:** deep dives, architecture overviews, conceptual guides, project context.
+- Abstract → concrete: definition → context → implementation/example.
+- Scaffolding: complex ideas built on established foundations.
+
+### Prompt / Task Definition (Functional)
+**For:** rcode tasks, prompts, system instructions, XML definitions.
+- Meta-first: inputs, usage constraints, context defined before instructions.
+- Separation of concerns: instructions (logic) separate from data (content).
+- Step-by-step: execution flow explicit and ordered.
+
+### Strategic / Context (Pyramid)
+**For:** PRDs, research reports, proposals, decision records.
+- Top-down: conclusion / status / recommendation starts the document.
+- Grouping: supporting context grouped logically below the headline.
+- Ordering: most critical information first.
+- MECE: arguments are Mutually Exclusive and Collectively Exhaustive.
+- Evidence: data supports arguments, never leads.
+
+---
+
+## Recommendation categories
+
+| Category | Use when |
+|---|---|
+| `CUT` | Section adds no value to the stated purpose; remove entirely |
+| `MERGE` | Two sections cover overlapping ground; combine |
+| `MOVE` | Critical information is buried, or details precede their setup |
+| `CONDENSE` | Section is needed but verbose — shorten significantly |
+| `QUESTION` | Decision the author needs to make (not the editor's call) |
+| `PRESERVE` | Element looks cuttable but actually serves comprehension — explicitly keep |
+
+---
+
+## HALT conditions
+
+- HALT with error if content is empty or fewer than 3 words.
+- HALT with error if `reader_type` is not `humans` or `llm`.
+- If no structural issues found: output "No substantive changes recommended — document structure is sound." (Valid completion, not an error.)
+
+---
+
+## Style guide override
+
+If a `style_guide` is provided, it overrides all generic principles in this skill — including human-reader principles, LLM-reader principles, structure-model selection, and the Microsoft Writing Style Guide baseline. The single exception is **content is sacrosanct**: never change what ideas say, only how they're expressed.

package/rcode/skills/core/rcode-help/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: rcode-help
+description: "Answers rcode questions and recommends the next skill to run, based on current project state."
+triggers:
+  # English
+  - "help"
+  - "rcode help"
+  - "what should I do next"
+  - "what can rcode do"
+  - "show me my options"
+  # Roman Urdu / Hindi
+  - "madad karo"
+  - "madad chahiye"
+  - "rcode mein kya karu"
+  - "agla kadam kya hai"
+  - "kya karu rcode mein"
+  # Arabic native
+  - "ساعدني"
+  - "مساعدة"
+  - "ما الخطوة التالية"
+  - "ماذا أفعل في ريحال"
+  - "كيف أبدأ"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+# rcode Help
+
+## Overview
+
+Help skill for rcode.
+
+## Purpose
+
+Help the user understand where they are in their rcode workflow and what to do next. Answer rcode questions when asked.
+
+## Desired Outcomes
+
+When this skill completes, the user should:
+
+1. **Know where they are** — which module and phase they're in, what's already been completed
+2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
+3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
+4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
+5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+
+## Data Sources
+
+- **Catalog**: `{project-root}/.rcode/catalog.json` — assembled manifest of all installed module skills
+- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/.rcode/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
+- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
+- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+
+## CSV Interpretation
+
+The catalog uses this format:
+
+```
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+```
+
+**Phases** determine the high-level flow:
+- `anytime` — available regardless of workflow state
+- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
+
+**Dependencies** determine ordering within and across phases:
+- `after` — skills that should ideally complete before this one
+- `before` — skills that should run after this one
+- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
+
+**Required gates**:
+- `required=true` items must complete before the user can meaningfully proceed to later phases
+- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
+
+**Completion detection**:
+- Search resolved output paths for `outputs` patterns
+- Fuzzy-match found files to catalog rows
+- User may also state completion explicitly, or it may be evident from the current conversation
+
+**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
+
+## Response Format
+
+For each recommended item, present:
+- `[menu-code]` **Display name** — e.g., "[CP] Create PRD"
+- Skill name in backticks — e.g., `rcode-create-prd`
+- For multi-action skills: action invocation context — e.g., "noor lets create a mermaid diagram!"
+- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Args if available
+
+**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
+
+## Constraints
+
+- Present all output in `{communication_language}`
+- Recommend running each skill in a **fresh context window**
+- Match the user's tone — conversational when they're casual, structured when they want specifics
+- If the active module is ambiguous, ask rather than guess
+
+## Output Format
+
+Status summary of current workflow position, then ordered list of recommended next skills with `[menu-code]` **Display name**, skill name in backticks, and description.
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Examples
+
+### Happy path
+**User:** "what should I do next?"
+**Result:** Detects PRD exists but no stories → recommends `rcode-create-epics-and-stories` → offers to run it
+
+### Edge case
+**User:** "help" in an empty project
+**Result:** No artifacts found → recommends starting with `rcode-scaffold-project` or `rcode-init`
+
+### Negative boundary
+**User:** "help me write a React component"
+**Result:** Not a rcode workflow question → route to `rcode-dev-story` or answer directly
+
+## Memory Bank Hooks
+
+- **Reads:** nothing — `help` is pure reference output
+- **Writes:** nothing — read-only

package/rcode/skills/core/rcode-incident-record/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: rcode-incident-record
+description: Generate a change record + post-mortem in one flow.
+triggers:
+  - "incident record"
+  - "post mortem"
+  - "change record"
+  - "document this incident"
+  - "write a postmortem"
+  - "record this change"
+  - "rca write up"
+  - "incident summary"
+user-invocable: true
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+## Overview
+
+Every production change deserves a record; every incident deserves a post-mortem. This skill produces both in the documented rcode format, so the team builds an institutional memory rather than repeating the same Slack-message-as-archaeology pattern. Output goes to the Memory Bank automatically — `.rcode/memory/change-records/` for changes, `.rcode/memory/incidents/post-mortems/` for incidents.
+
+## Two formats
+
+### Change record (`change-records/YYYYMMDD-NNN.md`)
+
+Mirrors the rcode template at `template/docs/change_records/20250514-001.md`. Use for any deploy, schema change, infra change, or anything you'd want to find again in 6 months.
+
+```markdown
+### Change ID
+`YYYYMMDD-NNN`
+
+### Date of Change
+YYYY-MM-DD
+
+### Requester
+<name + role>
+
+### Change Owner
+<name + team>
+
+### Change Category
+Backend (BE) | Frontend (FE) | Infra | Data | Security
+
+### Change Type
+Hotfix | Standard release | Schema migration | Config change
+
+### Change Description
+<one paragraph — what changed, why, what users see>
+
+### Related Tickets / References
+- GitHub PR: #N
+- Issue: #M
+- Related change records: <links>
+
+### Risk Assessment
+Low | Medium | High | Emergency
+- <specific risks identified>
+
+### Deployment Method
+<Helm | Compose | manual | gradual rollout %>
+
+### Approval
+Approved by: <name>
+Approval date: YYYY-MM-DD
+
+### Rollback Plan
+<exact steps to revert; test the rollback in staging first if possible>
+
+### Verification & Outcome
+Successful | Partial | Rolled back
+- <verification steps and outcomes>
+
+### Post-Change Notes
+<anything useful for future-you>
+```
+
+### Post-mortem (`incidents/post-mortems/YYYYMMDD-<slug>.md`)
+
+For resolved incidents. Format below.
+
+```markdown
+# Incident — <one-line headline>
+
+**Date:** YYYY-MM-DD
+**Duration:** <X minutes>
+**Severity:** SEV1 (customer-facing data loss) | SEV2 (degraded service) | SEV3 (internal)
+**Detection:** <how we noticed — Sentry alert, customer report, internal monitoring>
+**Resolution:** <one sentence>
+
+## Timeline
+
+- HH:MM — <event>
+- HH:MM — <event>
+- HH:MM — <resolution>
+
+## Root cause
+
+<one paragraph, mechanism not symptom>
+
+## Contributing factors
+
+- <factor 1>
+- <factor 2>
+
+## What worked
+
+- <what helped us recover quickly>
+
+## What didn't
+
+- <what slowed us down — be honest, not defensive>
+
+## Action items
+
+- [ ] <preventive measure> — owner — by when
+- [ ] <detective measure> — owner — by when
+- [ ] <documentation update> — owner — by when
+
+## Memory Bank update
+
+- known-issues.md: <removed | updated>
+- decisions.md: <appended new decision if relevant>
+```
+
+## Workflow
+
+1. **Detect type:** is this a planned change (change record) or a resolved incident (post-mortem)? Both can apply if a change caused an incident.
+2. **Gather facts.** From Sentry, PRs, deploy logs, Slack threads. Quote verbatim where useful.
+3. **Generate the document** using the appropriate template.
+4. **Save to the Memory Bank** at the right path. ID format `YYYYMMDD-NNN` (sequence per day).
+5. **Update related Memory Bank files:**
+   - Remove the issue from `known-issues.md` if a real fix shipped.
+   - Append a decision to `decisions.md` if the post-mortem produced one.
+6. **Schedule a follow-up review** if action items remain — 1 week typical.
+
+## Output Format
+
+The skill writes the file directly. Output to the user is a confirmation:
+
+```
+✓ Change record saved to .rcode/memory/change-records/20260426-001.md
+   Type: <type>
+   Severity / Risk: <level>
+   
+Memory Bank updates:
+  → known-issues.md: removed entry "<title>"
+  → decisions.md: appended decision "<title>"
+
+Action items: <count> open, <count> due this week
+```
+
+## Examples
+
+**Happy path — change record** — Deployed Postgres 16 upgrade. Auto-generates change-records/20260426-001.md with risk: medium, rollback: Helm rollback to previous chart version, verification: ground-truth queries pass. Approved by Hanzla, deployed gradually with 24h soak.
+
+**Happy path — post-mortem** — Login broke for Arabic usernames for 3h. Root cause: client_encoding mismatch on a new Postgres replica. Timeline + actions + Memory Bank update (remove the bug from known-issues, add a CI check that asserts client_encoding = utf8). One follow-up: add ground-truth tests for non-ASCII auth.
+
+**Negative — "we resolved it on Slack, no need for a doc"** — Refuse. Slack threads decay; Memory Bank persists. The 10 minutes spent writing the post-mortem saves an hour the next time the same class of bug appears.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rcode/memory/incidents/known-issues.md` (so we know what to clean up)
+- **Writes:** `.rcode/memory/change-records/YYYYMMDD-NNN.md` (changes); `.rcode/memory/incidents/post-mortems/YYYYMMDD-<slug>.md` (incidents); plus updates to `known-issues.md` and `decisions.md` as side-effects

package/rcode/skills/core/rcode-index-docs/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: rcode-index-docs
+description: "Generates or updates an index.md to reference all docs in the folder."
+triggers:
+  - "index docs"
+---
+@.rcode/references/karpathy-guidelines.md
+
+
+# Index Docs
+
+**Goal:** Generate or update an index.md to reference all docs in a target folder.
+
+
+## Overview
+
+Index docs skill for rcode.
+
+## EXECUTION
+
+### Step 1: Scan Directory
+
+- List all files and subdirectories in the target location
+
+### Step 2: Group Content
+
+- Organize files by type, purpose, or subdirectory
+
+### Step 3: Generate Descriptions
+
+- Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename
+
+### Step 4: Create/Update Index
+
+- Write or update index.md with organized file listings
+
+
+## OUTPUT FORMAT
+
+```markdown
+# Directory Index
+
+## Files
+
+- **[filename.ext](./filename.ext)** - Brief description
+- **[another-file.ext](./another-file.ext)** - Brief description
+
+## Subdirectories
+
+### subfolder/
+
+- **[file1.ext](./subfolder/file1.ext)** - Brief description
+- **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+### another-folder/
+
+- **[file3.ext](./another-folder/file3.ext)** - Brief description
+```
+
+
+## HALT CONDITIONS
+
+- HALT if target directory does not exist or is inaccessible
+- HALT if user does not have write permissions to create index.md
+
+
+## VALIDATION
+
+- Use relative paths starting with ./
+- Group similar files together
+- Read file contents to generate accurate descriptions - don't guess from filenames
+- Keep descriptions concise but informative (3-10 words)
+- Sort alphabetically within groups
+
+## Workflow
+
+1. Read the user request and extract key parameters.
+2. Execute the skill logic as described in the Overview.
+3. Return output in the format specified below.
+
+## Output Format
+
+- Structured Markdown response
+- Headers for each section
+- Concise, actionable content
+
+## Examples
+
+### Happy path
+**User:** "create an index of all files in ./docs"
+**Result:** Scans docs/ → groups by type → generates index.md with relative links and descriptions
+
+### Edge case
+**User:** "index docs" + folder with 200 files and nested subdirectories
+**Result:** Groups by subdirectory, generates hierarchical index with descriptions read from each file
+
+### Negative boundary
+**User:** "document this project"
+**Result:** Not indexing → route to `rcode-document-project`
+- Skip hidden files (starting with .) unless specified
+
+## Memory Bank Hooks
+
+- **Reads:** every doc in the indexing scope
+- **Writes:** the index file at the configured output path; does NOT modify `.rcode/memory/` (use `rcode-memory-distill` for memory bank index regeneration)