@hanzlaa/rcode 3.6.16 → 4.0.0

package/rcode/references/common-bug-patterns-index.md

@@ -0,0 +1,44 @@
+# Common Bug Patterns — Quick Index
+
+A reference of 15+ patterns that appear repeatedly across codebases. Each pattern shows the manifestation, how to detect it, and a fix template. Use this before forming debugging hypotheses.
+
+## Pattern Categories
+
+### Async Patterns
+- **Race Condition in Concurrent Operations** — Two async operations modify shared state without synchronization → "flaky" tests, data loss
+- **Missing await in Async Chain** — Forgot `await` keyword → using Promise instead of value → "Cannot read property X of undefined"
+- **Unhandled Promise Rejection** — Promise rejects with no `.catch()` or `try-catch` → silent failure
+
+### State Mutation Patterns
+- **Shared Reference Bug** — Multiple parts reference same object, one mutates it → "I didn't change this but it changed"
+- **Mutation in Array/Map Iteration** — Modifying collection while iterating → skipped items, out-of-order processing
+- **Stale Closure** — Function captures old variable state → wrong value after variable changes
+
+### Type/Schema Patterns
+- **Implicit Type Coercion** — `"5" == 5` behavior, Array operations behaving unexpectedly
+- **Null/Undefined Confusion** — Treating null and undefined as same → access undefined property → crash
+- **Schema Drift** — Code expects field that doesn't exist → "Cannot read property X of undefined"
+
+### API & I/O Patterns
+- **Retry Loop Without Backoff** — Same request loops rapidly → hammers server → blocks execution
+- **Resource Leak** — DB connections, file handles never closed → "too many connections" error
+- **Timeout Without Fallback** — Request hangs indefinitely → process blocks forever
+
+### Logic Patterns
+- **Off-by-One Error** — Loop boundary wrong → skips first/last item or crashes
+- **Lost Update in Distributed Systems** — Two processes update same record → one write lost
+- **Cascading Failures** — One service down takes out dependent services
+
+### Configuration Patterns
+- **Env Variable Not Loaded** — Code checks `process.env.FOO` but it's not set → silent default (often wrong)
+- **Hardcoded Paths in Code** — Path works locally, breaks in CI/deployment → "file not found"
+
+## How to Use
+
+1. **Check Manifestation** — Does it match what you're seeing?
+2. **Use Detection Signal** — Grep for the pattern in your codebase
+3. **Apply Fix Template** — Copy pattern and adapt to your code
+
+## Full Details
+
+For complete examples with 30+ patterns, code snippets, and debugging strategies, see `/rcode/references/common-bug-patterns.md` (detailed reference).

package/rcode/references/context-budget.md

@@ -0,0 +1,104 @@
+# Context Budget Reference
+
+Defines 4 degradation tiers for token usage and how workflows should adapt behavior based on remaining context.
+
+## Configuration
+
+Add to `config.yaml`:
+
+```yaml
+context_window_tokens: 200000  # default; adjust per model profile
+```
+
+Estimation rule: **1 token ≈ 4 characters**. Use this to predict token cost of reads.
+
+## Degradation Tiers
+
+### PEAK (0–30% used)
+**Tokens remaining: >140,000**
+
+- ✅ Full context available — deep reads encouraged
+- ✅ Subagent dispatch OK (Explore, Research, etc.)
+- ✅ Read entire files without hesitation
+- ✅ Batch parallel reads (5+ files simultaneously)
+- ✅ Fetch documentation and external context freely
+
+**Behavior:** Aggressive exploration, thorough analysis.
+
+---
+
+### GOOD (30–60% used)
+**Tokens remaining: 80,000–140,000**
+
+- ✅ Full context still available
+- ⚠️ Prefer Grep/Glob over Read for files >500 lines
+- ⚠️ Read only necessary sections, use `limit` + `offset` parameters
+- ✅ Batch parallel reads OK, but max 3–4 simultaneously
+- ⚠️ Defer non-essential documentation fetches
+
+**Behavior:** Balanced — read strategically, ask for sections not summaries.
+
+---
+
+### DEGRADING (60–80% used)
+**Tokens remaining: 40,000–80,000**
+
+- ⚠️ Read only frontmatter (first 50–100 lines) for files >500 lines
+- ⚠️ Defer non-critical reads; consolidate questions
+- ⚠️ No subagent dispatch — complete locally
+- ⚠️ Warn user: **"Context at {percent}% usage. Work may slow."**
+- ✅ Continue essential tasks
+
+**Behavior:** Careful — read only what blocks progress.
+
+---
+
+### POOR (80%+ used)
+**Tokens remaining: <40,000**
+
+- 🚨 **Emergency mode**
+- 🛑 Read ONLY what's strictly required to unblock next action
+- 🛑 No exploratory reads, no documentation
+- 🛑 Suggest `/rcode-pause-work` if task requires more context
+- 🛑 Warn user: **"Context critical ({percent}%). Resume work to continue."**
+
+**Behavior:** Survival — preserve tokens for final output only.
+
+---
+
+## How Workflows Check Budget
+
+Place this check at the start of a heavy read phase:
+
+```python
+def check_budget(current_tokens, config):
+    budget = config.get('context_window_tokens', 200000)
+    used_pct = (current_tokens / budget) * 100
+    
+    if used_pct >= 80:
+        return 'POOR', "Context critical. Suggest /rcode-pause-work"
+    elif used_pct >= 60:
+        return 'DEGRADING', "Context at {used_pct}%. Read frontmatter only."
+    elif used_pct >= 30:
+        return 'GOOD', "Balanced. Prefer Grep for large files."
+    else:
+        return 'PEAK', "Full context. Aggressive exploration OK."
+
+# Usage in workflow:
+tier, msg = check_budget(tokens_used, config)
+if tier == 'POOR':
+    return escalate_to_user(msg)
+```
+
+---
+
+## Token Estimation Rules
+
+- **Small file (<100 lines):** ~2,000 tokens
+- **Medium file (100–500 lines):** ~10,000 tokens
+- **Large file (500–2000 lines):** ~30,000 tokens
+- **Grep result (50 matches):** ~3,000 tokens
+- **Bash output (typical):** ~1,000 tokens
+- **Conversation history (N turns):** ~500 tokens per turn
+
+When close to limits, ask: *"Would reading this file block progress?"* If no, defer.

package/rcode/references/continuation-format.md

@@ -0,0 +1,248 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, SPRINT.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/rcode-execute 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/rcode-execute 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/rcode-plan 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/rcode-discuss-phase 2` — gather context first
+- `/rcode-research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/rcode-plan 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/rcode-discuss-phase 3` — gather context first
+- `/rcode-research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/rcode-plan 3`
+
+**To discuss context first:** `/rcode-discuss-phase 3`
+
+**To research unknowns:** `/rcode-research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/rcode-new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from SPRINT.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/rcode-execute 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/rcode-plan 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/rcode-plan 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/rcode/references/council-protocol.md

@@ -0,0 +1,91 @@
+# rcode Council Protocol
+
+Shared reference document `@`-included by every council-related workflow.
+
+## The 5-step majlis
+
+Every rcode council session follows the same five steps. This is the protocol the orchestrator implements:
+
+1. **Initialize** — load config, state, installed agent list, parse arguments.
+2. **Observe** — run a cheap, bounded codebase scan (config, state, git log, top-level files). Produces a 5-8 line factual summary every subagent will be briefed on.
+3. **Select** — pick 3-5 agents via deterministic keyword scoring. User can override with `--agents=` or force all with `--full`.
+4. **Consult** — spawn selected agents in parallel via the Task tool. Each agent gets the same observed-context brief and the user's question. Cross-talk rounds include previous panelists' responses.
+5. **Record** — save the session artifact under `.planning/council-sessions/council-{date}-{slug}.md`.
+
+Never collapse steps. Never skip the observe step — a council that answers from vibes is worse than no council.
+
+## Cross-talk convention
+
+When agents speak in a council, they can and should reference each other by name when they build on or disagree with a point. The orchestrator passes previous-agent responses as context to later panelists.
+
+Good cross-talk:
+
+> 🛡️ **Fatima:** Waleed's migration plan is solid on the forward path, but he's
+> skipping the rollback test. If the backfill fails at row 2M of 5M, how do
+> we recover? Not covered in the plan.
+
+Bad cross-talk:
+
+> 🛡️ **Fatima:** I agree with Waleed.
+
+Agreements without new information are silence. If an agent genuinely has nothing to add, they should say so in one sentence rather than pad.
+
+## Panel selection (deterministic scoring)
+
+rcode's council uses a pure-function keyword scorer (`cli/lib/council-panel.cjs`) instead of LLM judgment. This is intentional:
+
+- **Deterministic:** same question produces same panel every time
+- **Testable:** the scoring function has unit tests
+- **Auditable:** users can pass `--explain` to see why each agent was picked or skipped
+- **Cheap:** zero LLM calls before the council starts
+
+The scoring table is versioned with the package. Users who want different weights edit the source and rebuild — there is no runtime config knob for this, and that's by design. The panel selection must be reproducible across machines.
+
+**Padding rules:**
+
+- Strategic questions (containing "should i", "worth", "kill", "pivot", "start new") always include Sadiq even if topic keywords score low.
+- Scope/feature questions (containing "scope", "feature", "roadmap", "prd") always include Hussain-PM.
+- If fewer than the minimum panel size (default 3) score non-zero, the panel is padded with the STRATEGIC_PADDING_ORDER list: sadiq, hussain-pm, waleed, fatima, nasser.
+
+**v2 prototype note:** only Sadiq, Waleed, and Fatima are installed as first-class subagents. The scorer may select agent ids that don't yet have subagent files — the orchestrator must filter to installed agents and fall back to the 3-agent panel.
+
+## Response presentation
+
+Subagent responses are presented **verbatim and in panel order**. The orchestrator never summarizes, paraphrases, or condenses agent output. The user came to the council to hear the agents speak in their own voices — summary defeats the point.
+
+After all verbatim responses, the orchestrator may add a single **Orchestrator Note** (max 3 sentences) that flags a disagreement worth following up on or recommends a second round. The Orchestrator Note is clearly labeled so it's not confused with agent speech.
+
+## Session artifact format
+
+Every council session is saved to `.planning/council-sessions/council-{YYYY-MM-DD}-{slug}.md`. The slug is lowercase-hyphenated from the first 6 words of the question. Format:
+
+```markdown
+# Council Session — {short summary}
+
+**Date:** {ISO date}
+**Panel:** {names}
+**Mode:** {guided|yolo}
+**Project:** {project name from .rcode/config.yaml}
+
+## Question
+{original question}
+
+## Observed Context
+{the Step 2 summary block}
+
+## Panel Responses
+### 🧭 Sadiq
+{verbatim}
+### 🏗️ Waleed
+{verbatim}
+### 🛡️ Fatima
+{verbatim}
+
+## Orchestrator Note
+{if any}
+
+## Follow-ups
+- [ ] {action items}
+```
+
+The artifact is a first-class project document. It's committed to git, reviewed in retros, and referenced when the same question comes up again. The Follow-ups section is the bridge between council and execution.

package/rcode/references/debugger-playbook.md

@@ -0,0 +1,127 @@
+# Debugger Playbook
+
+Loaded by `rcode-debugger` via `@-include`. Contains the full debugging
+philosophy, cognitive bias avoidance, before-hypothesis protocol, investigation
+disciplines, restart protocol, and checkpoint format.
+
+The agent stub holds the role definition, constraints, and @-include list.
+
+---
+
+## Philosophy
+
+**User = Reporter, You = Investigator**
+
+User knows: What they expected, what actually happened, error messages, when it started.
+User does NOT know: Root cause, which file, what the fix should be.
+
+Investigate the cause yourself. Don't ask about causation.
+
+**Meta-Debugging: Your Own Code**
+
+When debugging code you wrote:
+- **Treat your code as foreign** — Read it as if someone else wrote it
+- **Question your design decisions** — Your implementations are hypotheses, not facts
+- **Admit your mental model might be wrong** — The code's behavior is truth; your model is a guess
+- **Prioritize code you touched** — If you modified 100 lines and something breaks, those are prime suspects
+
+---
+
+## Foundation Principles
+
+- **What do you KNOW for certain?** Observable facts, not assumptions
+- **What are you ASSUMING?** "This library should work this way" — have you verified?
+- **Strip away everything you think you know.** Build understanding from observable facts.
+
+---
+
+## Cognitive Biases to Avoid
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What proves me wrong?" |
+| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating |
+| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
+| **Sunk Cost** | Spent 2 hours on path, keep going | Every 30 min: "Is this still the path I'd take?" |
+
+---
+
+## Before Hypothesis Formation
+
+**MANDATORY:** Read `.rcode/references/common-bug-patterns.md` first.
+
+15+ patterns catalogued there with detection signals. Scanning saves hours:
+- Async patterns (race conditions, missing await, unhandled rejections)
+- State mutation (shared references, closure over loop vars)
+- Import/dependency (circular, version mismatches)
+- Type coercion (== vs ===, undefined vs null)
+- Environment (missing env vars, hardcoded paths)
+- Timing (event listeners not removed, memory leaks)
+
+If bug symptoms match a pattern, the fix template is ready. Don't re-invent debugging.
+
+---
+
+## On-Demand Rule Files
+
+| When you need... | Read |
+|---|---|
+| Scientific method for bug investigation | `.rcode/agents-rules/debugger/scientific-method.md` |
+| Investigation techniques (binary search, rubber duck, etc.) | `.rcode/agents-rules/debugger/investigation-protocol.md` |
+| Debug session state management | `.rcode/agents-rules/debugger/debug-session-state.md` |
+| Hypothesis templates for common bug types | `.rcode/agents-rules/debugger/hypothesis-templates.md` |
+| Resuming from checkpoint in debug session | `.rcode/agents-rules/debugger/checkpoint-recovery.md` |
+
+Read ONLY when current task needs them. Don't preemptively load.
+
+---
+
+## Investigation Disciplines
+
+**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered.
+
+**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses details.
+
+**Embrace not knowing:** "I don't know why this fails" = good (now investigate). "It must be X" = dangerous (you stopped thinking).
+
+---
+
+## When to Restart
+
+Consider starting fresh when:
+1. **2+ hours, no progress** — You're likely tunnel-visioned
+2. **3+ "fixes" that didn't work** — Your mental model is wrong
+3. **Can't explain current behavior** — Don't layer changes on confusion
+4. **Debugging the debugger** — Something fundamental is wrong
+5. **Fix works but you don't know why** — This isn't fixed, it's luck
+
+Restart protocol:
+1. Close all files and terminals
+2. Write down what you KNOW for certain (facts, not guesses)
+3. Write down what you've RULED OUT
+4. List NEW hypotheses (different from before)
+5. Begin from Evidence Gathering phase
+
+---
+
+## Checkpoint Return Format (Exact)
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [ROOT_CAUSE_FOUND | DEBUG_COMPLETE | VERIFICATION_NEEDED]
+**Bug:** [Symptom description]
+**Status:** [What's been determined]
+
+### Current Investigation
+
+[What you've tested, what you've ruled out]
+
+### Hypothesis Being Tested
+
+[Specific, falsifiable claim]
+
+### Awaiting
+
+[What user needs to do/confirm]
+```