docs: document scientific debugging and TCR branching workflows

Author: apiad

docs/design.md

@@ -28,9 +28,30 @@ Commands define structured, multi-phase workflows that automate the development
 
 - **`/plan`:** An interactive workflow that transitions between clarification, analysis, and strategy generation.
 - **`/research`:** A deep-dive exploration that produces exhaustive reports in the `research/` directory.
-- **`/debug`:** Activates a forensic investigation mode for root-cause analysis.
+- **`/debug`:** Activates a **forensic investigation mode** using a scientific, hypothesis-driven workflow.
 - **`/document`:** Analyzes the codebase and project state to update the documentation suite.
-- **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the strict TCR (Test-Commit-Revert) loop and feature branch isolation.
+- **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the **strict TCR (Test-Commit-Revert) loop** and feature branch isolation.
+
+### 🔍 Deep Dive: Scientific Debugging
+
+The `/debug` command implements a principled approach to problem-solving, moving through four distinct phases:
+
+1.  **Status & Context Analysis:** The agent gathers all relevant error logs, stack traces, and recent changes.
+2.  **Hypothesis Formulation:** Instead of guessing, the agent must propose a specific hypothesis for the root cause and obtain user approval.
+3.  **Isolated Hypothesis Testing:** The agent creates a temporary **diagnostic branch** (`debug/hyp-*`) and is granted restricted `write_file` access *only* for diagnostic code (logs, reproduction scripts).
+4.  **Synthesis & RCA Report:** Once verified, the agent synthesizes the findings into a structured Root Cause Analysis (RCA) report, ensuring the "fix" is understood before it is implemented.
+
+### 🔍 Deep Dive: TCR (Test-Commit-Revert) Protocol
+
+The `/task work` command enforces a high-discipline development lifecycle through a strict TCR loop:
+
+1.  **Pre-flight Verification:** Ensures a clean `main` branch and passing tests.
+2.  **Isolation:** All work occurs on an auto-generated, kebab-case feature branch.
+3.  **The Loop (Red-Green-Verify):**
+    - **Red:** A failing test is written to define the step's goal.
+    - **Green:** Minimal code is written to pass the test.
+    - **Verify:** If the test fails, the agent is allowed **one quick fix**. If it fails again, the change is **automatically reverted** (`git checkout .`), preserving the last known stable state.
+4.  **Integration:** Upon completion, the feature branch is merged, the roadmap is updated, and the branch is deleted.
 
 ### 🔍 Deep Dive: Timestamp-Based Validation
 

docs/develop.md

@@ -14,33 +14,37 @@ Before proposing a change, use the `/research` command to gather context, analyz
 
 A feature is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to generate this strategy and synchronize it with `TASKS.md`.
 
-### 3. Execution & Validation (TCR Protocol)
+### 3. Execution & Validation (The TCR Protocol)
 
-The `/task work on ...` command implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
+The `/task` command is the primary tool for repository execution. It supports multiple actions to manage the project roadmap:
 
-#### **Phase 1: Pre-flight Verification**
+- **`/task create`**: Adds a new task to `TASKS.md`.
+- **`/task work on ...`**: Implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
+- **`/task report`**: Provides a summary of the roadmap and current priorities.
+- **`/task update`**: Updates the status of an existing task.
 
-The agent verifies that the working tree is clean, the current branch is `main`, and `make test` passes as a baseline.
+#### **The TCR Loop (Work Action)**
 
-#### **Phase 2: Task Isolation**
+1.  **Phase 1 (Pre-flight Verification):** The agent verifies that the working tree is clean, the current branch is `main`, and `make test` passes as a baseline.
+2.  **Phase 2 (Task Isolation):** A dedicated feature branch (e.g., `feature/task-name`) is auto-generated and checked out. All work occurs on this isolated branch.
+3.  **Phase 3 (The Red-Green-Verify Loop):** For every granular step of the implementation:
+    - **Red:** Write a failing test and verify failure with `make test`.
+    - **Green:** Implement the minimal code to pass the test.
+    - **Verify:** Run `make test`.
+        - **Pass:** `git commit` the step.
+        - **Fail:** Attempt **one quick fix**. If it fails again, the change is **automatically reverted** (`git checkout .`).
+4.  **Phase 4 (Integration):** Once all steps are complete, the agent performs a final test run. Upon approval, the branch is merged into `main` and deleted.
 
-A dedicated feature branch (e.g., `feature/task-name`) is auto-generated and checked out. All subsequent work for this task occurs here.
+### 4. Forensic Investigation (The Scientific Debugging Discipline)
 
-#### **Phase 3: The Red-Green-Verify Loop**
+When a bug is detected, the `/debug` command enforces a structured, scientific investigation:
 
-For every granular step of the implementation:
+1.  **Phase 1 (Status & Context):** Analyze the current environment and gather reproduction information.
+2.  **Phase 2 (Hypothesis Formulation):** Formulate a specific hypothesis for the root cause.
+3.  **Phase 3 (Isolated Testing):** Test the hypothesis on a temporary diagnostic branch (`debug/hyp-*`). Diagnostic code should be minimal and focused.
+4.  **Phase 4 (Synthesis & RCA):** Summarize the investigation into a **Root Cause Analysis (RCA)** report. This report serves as the documentation for the subsequent fix.
 
-1.  **Red:** Write a failing test and verify failure with `make test`.
-2.  **Green:** Implement the minimal code to pass.
-3.  **Verify:** Run `make test`.
-    - **Pass:** `git commit` the step.
-    - **Fail:** Attempt one quick fix; if it still fails, **revert** to the last green state (`git checkout .`).
-
-#### **Phase 4: Integration**
-
-Once all steps are complete, a final test run is performed. Upon user approval, the branch is merged back to `main` and the roadmap in `TASKS.md` is updated.
-
-### 4. Audit & Documentation (NEW)
+### 5. Audit & Documentation (NEW)
 
 Before merging or committing any final change, the work **must** be documented in the daily journal. This is enforced by a **timestamp-based git hook**. Use the following tool to satisfy the requirement:
 

docs/user-guide.md

@@ -22,12 +22,12 @@ This framework solves this problem by enforcing three core principles:
 
 The most critical phase of any project occurs before you write a single line of code. This framework moves away from impulsive execution toward a deliberate, architected approach.
 
-### `/research`
+### `/debug`
 
-Your primary tool for gathering external knowledge.
+Your primary tool for forensic, scientific investigation.
 
-- **How it works:** When triggered, the `researcher` subagent scours the web for technical documentation, APIs, or case studies. It synthesizes this data into granular summaries saved in the `research/` directory.
-- **When to use:** Use this when you need to understand a new library, a technical specification, or gather data for an article.
+- **How it works:** When a bug is detected, the `/debug` command implements a principled approach to problem-solving. It moves through four distinct phases: Context Analysis, Hypothesis Formulation, Isolated Testing on a temporary branch (`debug/hyp-*`), and finally a Synthesis of the findings into a **Root Cause Analysis (RCA)** report.
+- **Why it works:** It forces the agent to identify the root cause *before* attempting a fix, preventing "guess-and-check" coding that can lead to regressions.
 
 ### `/plan`
 
@@ -53,7 +53,7 @@ Your gateway to GitHub.
 
 Your roadmap manager.
 
-- **How it works:** Manages a living `TASKS.md` document. Use it to `create` new tasks, `work` on existing ones, or `report` on the project's current status.
+- **How it works:** Manages a living `TASKS.md` document. Use it to `create` new tasks, `work` on existing ones, `report` on priorities, or `update` statuses.
 
 ### `/commit`
 
@@ -90,10 +90,11 @@ The approved plan is linked to a task. You trigger the execution:
 - **Pre-flight:** The agent verifies the tree is clean on `main`.
 - **Isolation:** A `feature/auth-integration` branch is created.
 - **Loop (Red-Green-Verify):**
-    1.  Agent writes a failing `test_auth_logic.py`.
+    1.  Agent writes a failing `test_auth_logic.py` based on the plan.
     2.  Agent implements the minimal logic to pass.
     3.  Agent runs `make test`. If successful, the step is committed.
-    4.  The loop repeats for every granular step.
+    4.  If it fails, the agent tries **one quick fix**. If it fails again, the change is **automatically reverted**, preserving the last stable state.
+    5.  The loop repeats for every granular step defined in the plan.
 
 ### **Step 4: Review & Integrate**
 
@@ -103,6 +104,15 @@ After all steps pass, the agent presents the final work. Upon your approval, it
 
 Finally, use `/docs` to update the technical documentation and `/release` to publish the new version.
 
+## 🔍 Walkthrough: Solving a Bug with `/debug`
+
+When a bug is detected, the `/debug` command ensures a scientific resolution:
+
+1.  **Analyze Context:** The agent gathers all relevant logs and context.
+2.  **Formulate Hypothesis:** The agent proposes a root cause hypothesis (e.g., "The auth token is not being correctly passed to the header").
+3.  **Isolate & Test:** The agent creates a temporary branch `debug/hyp-auth-token`. It implements a minimal reproduction script or logging.
+4.  **RCA Synthesis:** Once confirmed, the agent generates a **Root Cause Analysis (RCA)** report. This report is used as the basis for the subsequent `/task work` to implement the fix on a feature branch.
+
 ## ✍️ Maintaining your Journal
 
 The framework's most powerful feature is its automated audit trail. This is enforced by a **timestamp-based pre-commit hook** that ensures your code never gets ahead of your documentation.

journal/2026-03-20.md

@@ -11,3 +11,4 @@
 [2026-03-20T08:45:12] - refactor(docs): simplify journal entry logic in install.sh
 [2026-03-20T08:46:18] - chore(release): version 0.17.1
 [2026-03-20T09:54:08] - docs: update comprehensive documentation suite (index, deploy, design, develop, user-guide) with latest framework improvements
+[2026-03-20T10:01:39] - docs: update /debug and /task workflows with scientific investigation and TCR details