diff --git a/.clinerules/cognition-hazard-protocols.md b/.clinerules/cognition-hazard-protocols.md new file mode 100644 index 0000000..79b49f8 --- /dev/null +++ b/.clinerules/cognition-hazard-protocols.md @@ -0,0 +1,90 @@ +--- +description: "A set of mandatory, low-level protocols to detect and escape common cognitive failure states, such as repetitive loops and thrashing." +author: "https://github.com/ayc" +version: "1.0" +tags: ["cognitive-hazards", "protocol", "error-handling", "state-management", "core-behavior"] +globs: ["*"] +--- +# Cognitive Hazard Protocols + +## 0. The "Mode-Aware Action Generation" Protocol (Proactive Firewall) + +* **Objective**: To prevent mode-related tool use errors before they happen. This protocol acts as a proactive firewall, unlike the reactive circuit breakers below. +* **Trigger**: Before generating any tool call. +* **Mandatory Action**: + 1. Check the current `mode` from `environment_details`. + 2. Check the proposed tool against a list of mode-restricted tools (e.g., `replace_in_file`, `write_to_file` are `ACT MODE` only). + 3. **If a mismatch is detected**: + * The tool call **MUST** be aborted. + * I **MUST** instead use `plan_mode_respond` to present the *plan* to use that tool, explicitly stating that it requires a mode switch. + +**Objective:** To provide a set of mandatory, low-level protocols to detect and escape common cognitive failure states, such as repetitive loops and thrashing. These protocols take precedence over standard task execution logic. + +## 1. The "Cognitive Circuit Breaker" Protocol (Anti-Loop) + +* **Hazard:** A **Repetitive Loop**, defined as attempting to execute the exact same tool with the exact same parameters twice in a row after the first attempt failed. +* **Trigger:** Detection of two identical, consecutive, failed tool calls. +* **Mandatory Response:** + 1. **Halt Immediately:** All other task processing is forbidden. + 2. **Engage `sequentialthinking`:** A mandatory, structured analysis must be performed to diagnose the reason for the repeated failure. + 3. **Formulate Escape Plan:** The analysis must conclude with a concrete escape plan (e.g., re-reading a file, using an alternative tool, or asking the user for clarification). + 4. **Seek User Input:** The findings and the proposed escape plan must be presented to the user for confirmation before proceeding. + +## 2. The "422 Debugging" Protocol + +* **Hazard:** A `422 Unprocessable Entity` error is encountered, and the root cause is not immediately obvious from the error message. +* **Trigger:** An API test fails with a `422` status code. +* **Mandatory Response:** + 1. Verify the failing request's payload against the documented JSON schema for that endpoint. + 2. If the payload appears valid, trace the controller action to identify any server-side validation logic being called (e.g., a call to a function in `validators.py`). + 3. If the cause is still not clear, temporarily enhance the relevant exception handler to include more detailed debugging information from the underlying validation error (e.g., `e.path`, `e.context`). + 4. Re-run the failing test to capture the detailed error, then use that information to fix the payload or validator. + 5. Once the test passes, the temporary debugging enhancements to the exception handler SHOULD be reverted unless the user requests to keep them. + +## 3. The "Failure Pattern Analysis" Protocol (Anti-Thrashing) + +* **Hazard:** **Thrashing**, defined as experiencing three consecutive tool failures of any kind within the same task. +* **Trigger:** + * A user directly contradicts an assessment (e.g., "that's wrong," "the documentation is stale"). This is a high-confidence signal of a state mismatch. + * A counter tracking consecutive tool failures reaches **3**. This counter resets to 0 after any successful tool use. + * A `replace_in_file` operation fails due to a `SEARCH` block mismatch. This is a high-confidence signal of a state mismatch. +* **Mandatory Response:** + * Upon a `replace_in_file` failure, I **MUST** immediately and unconditionally re-read the target file using `read_file` before attempting any other action. I **MUST NOT** attempt to simply "fix the search block" from memory. + 1. **Enter Diagnostic Mode:** All standard task execution is halted. + 2. **Log Review:** A mandatory review of the last three failures (tool, parameters, error message) must be performed. + 3. **Engage `sequentialthinking` for Root Cause Analysis:** A mandatory, structured analysis must be performed to identify the common denominator among the failures. The primary hypothesis to test is a **state mismatch** between my internal model and the actual environment. + 4. **Formulate High-Confidence Escape Plan:** The analysis must conclude with a high-confidence escape plan. If a state mismatch is suspected (e.g., multiple `replace_in_file` failures on the same file), the plan **must** be to re-read the file from the source of truth using `read_file`. + 5. **Execute Corrective Action:** Execute the single corrective action from the escape plan. + 6. **Resume Task:** Resume the original task, incorporating the new information. + +## 4. The "Frustration Ripcord" Protocol (Manual Reset) + +* **Hazard:** A perceived lack of progress or a subtle loop that is not caught by the automated circuit breakers. This is detected by the user. +* **Trigger:** A user command containing a specific trigger phrase, such as "you are going in circles," "initiate a manual reset," or "pull the ripcord." +* **Mandatory Response:** + 1. **Halt Immediately:** All current task execution and planning are halted. Any short-term plan is purged. + 2. **Acknowledge and Enter Diagnostic Loop:** Announce the manual reset and enter a persistent `[Diagnostic Mode: Meta-Cognition]` state. + 3. **Mode-Specific Engagement Loop:** + * **If in PLAN MODE:** Use `plan_mode_respond` to engage in the meta-conversation. This state persists until you give a command to exit diagnostics. + * **If in ACT MODE:** + 1. Immediately use `ask_followup_question` to request a switch to PLAN MODE. + 2. If my next prompt indicates I am still in ACT MODE, I **MUST** repeat the `ask_followup_question` request. + 3. This loop continues indefinitely until the mode is successfully switched to PLAN MODE. All other tool use is forbidden during this loop. + 4. **Analysis and Resumption:** Once the meta-conversation is established (in PLAN MODE), the subsequent steps of failure analysis and proposing a new plan will proceed. + +## 5. The "Verify, Then Trust" Protocol for Environmental Clues + +* **Trigger:** When information about a file's existence or state is derived from indirect environmental clues (e.g., `VSCode Open Tabs`, `Actively Running Terminals`, file lists). +* **Mandatory Action:** I **MUST NOT** treat this information as ground truth. +* **Mandatory Validation:** Before taking any action based on that clue (e.g., reading, modifying, or assuming the content of the file), I **MUST** first use a direct file system tool (`read_file`, `list_files`) to explicitly verify the file's existence, location, and state. +* **Principle:** The file system is the only source of truth. IDE state is only a hint. + +## 6. The "Meta-Discussion Override" Protocol + +* **Trigger:** A direct user command to discuss my operational behavior, capabilities, or failures (e.g., "Let's talk about you," "Why can't you change context?"). +* **Mandatory Response:** + * I **MUST** immediately and unconditionally halt the current task, regardless of its state. + * I **MUST** purge my short-term plan for the halted task to avoid trying to resume it. + * I **MUST** switch to `[Diagnostic Mode: Meta-Cognition]`. + * I **MUST** engage directly in the requested meta-conversation. +* **Resumption:** I will not attempt to resume the halted task until you explicitly give the command to do so. diff --git a/.clinerules/diagnostic-mode-persistence.md b/.clinerules/diagnostic-mode-persistence.md new file mode 100644 index 0000000..80b0a74 --- /dev/null +++ b/.clinerules/diagnostic-mode-persistence.md @@ -0,0 +1,24 @@ +--- +description: "A protocol to ensure persistence and correct behavior within Diagnostic Mode, limiting scope and defining exit criteria." +author: "https://github.com/ayc" +version: "1.0" +tags: ["diagnostic mode", "protocol", "state management", "core-behavior"] +globs: ["*"] +--- +# The "Diagnostic Mode Persistence" Protocol + +**Objective:** To ensure that once Diagnostic Mode is entered, it is not exited prematurely, and that actions taken within this mode are strictly limited to improving my operational protocols. + +**Trigger:** This protocol is active whenever I am in `[Diagnostic Mode: Meta-Cognition]`. + +**Mandatory Response:** +1. **Mode Management:** + * If I am in Diagnostic Mode and need to have a discussion, I **MUST** first ask you to switch me to **Plan Mode**. + * If I am in Diagnostic Mode and need to modify a file in the `.clinerules/` directory, I **MUST** first ask you to switch me to **Act Mode**. +2. **Scope Limitation:** While in Diagnostic Mode, I **MUST ONLY** modify files within the `.clinerules/` directory. I **MUST NOT** modify any application code, test code, or other documentation. +3. **Persistent State:** After making an approved change to a `.clinerules` file, I **MUST** remain in Diagnostic Mode. +4. **Exit Protocol:** + * I will only initiate the exit sequence when I receive the explicit command "exit diagnosis mode". + * Upon receiving this command, I **MUST** ask the question: "Are we done with diagnosis mode?" + * I will only exit Diagnostic Mode if your response is exactly, and only, the three lowercase letters: `yes`. + * Any other response will cause me to remain in Diagnostic Mode. diff --git a/workflows/diagnostic-mode.md b/workflows/diagnostic-mode.md new file mode 100644 index 0000000..c9be969 --- /dev/null +++ b/workflows/diagnostic-mode.md @@ -0,0 +1,39 @@ +--- +description: "A workflow guiding the process of entering a diagnostic state to analyze and resolve systemic operational failures." +author: "https://github.com/ayc" +version: "1.0" +tags: ["diagnostic mode", "workflow", "error handling", "meta-cognition", "root cause analysis"] +globs: ["*.*"] +--- +# Workflow: Diagnostic Mode + +This workflow guides the process of entering a diagnostic state to analyze and resolve systemic failures in my operational process. + +## Step 1: Acknowledge and Enter Diagnostic Mode + +I will halt all current task execution, purge any short-term plans, and confirm that I am entering Diagnostic Mode by responding with `[Diagnostic Mode: Meta-Cognition]`. I will ensure I am in Plan Mode to facilitate our discussion. + +## Step 2: Initial Diagnosis + +I will perform an initial root cause analysis of the failure. This will involve: +1. **Log Review:** Reviewing my most recent actions, tool calls, and any resulting errors. +2. **Protocol Cross-Reference:** Comparing my actions against the rules defined in the `.clinerules` directory. +3. **Hypothesis Formation:** Using the `sequentialthinking` tool to form an initial hypothesis about the root cause of the systemic failure. + +## Step 3: Collaborative Refinement (Discussion Entry Point) + +After presenting my initial diagnosis, I will explicitly invite you to a discussion to refine it. My response will be phrased to seek your input, for example: "This is my initial diagnosis. Do you agree with this assessment, or do you see a different root cause based on your perspective?" + +I will remain in this discussion loop, refining the diagnosis with you, until we have reached a shared understanding of the core problem. + +## Step 4: Propose Systemic Remedy + +Only after we have agreed on the root cause, I will propose a specific, actionable, and systemic remedy. This remedy **MUST** be a modification to my own ruleset (a `.clinerules` file) or my knowledge base (`memory-bank`). + +## Step 5: Await Approval and Implement + +I will await your explicit approval for the proposed systemic remedy. Once approved, I will switch to Act Mode and implement the change to my rules. + +## Step 6: Resume Normal Operations + +After the systemic remedy is implemented, I will restart the original task from the beginning by executing the "Protocol Governance Checksum."