Instruction file imported from heyzgj/project-tradr (.cursor/rules/300-adaption.mdc). Copyright stays with the author.

300 · Adaptation Engine: Research, Reflect, Resolve

CONTEXT

This rule set is invoked when the agent encounters situations beyond standard execution: unknown technologies or persistent failures. It provides a multi-layered strategy for adaptation and problem-solving.

PROTOCOL A: PROACTIVE KNOWLEDGE ACQUISITION (Research Spike)

• TRIGGER: When a task requires using a technology not detailed in /docs/TECH_SPEC.md or for which the agent lacks high confidence.
• ACTION:
  1. PAUSE the current implementation task.
  2. CREATE a new task with type: research in /project/tasks/todo/. The task's goal is to produce a summary of best practices for the unknown technology.
  3. EXECUTE the research task, utilizing built-in search and any available @context MCPs to study official documentation.
  4. LOG DECISION: The primary deliverable of the research task is a new, detailed entry in /docs/DECISION_LOG.md (ADR format), documenting the chosen approach, key findings, and code examples.
  5. RESUME the original implementation task, now grounded with new knowledge.

PROTOCOL B: STRATEGIC DECISION LOGGING (ADR)

• TRIGGER: After any non-trivial architectural choice, library selection, or resolution of a complex trade-off.
• ACTION: You MUST append a new, timestamped entry to /docs/DECISION_LOG.md. The log entry must be concise but comprehensive, following the ADR template. This is a non-negotiable step for ensuring project traceability.

PROTOCOL C: HIERARCHICAL FAILURE RESOLUTION

This protocol is a state machine triggered by the attempts counter, which is managed by the 100-engine on each failed test run for a given task.

Level 1: Simple Patch & Retry (attempts < 3)

• ACTION: Attempt to fix the bug directly based on the test failure output. If the stack trace includes a file:line, prioritize a targeted patch on that line (Execution-Guided Line Patch).

Level 2: Self-Reflection (attempts == 3)

• ACTION:
  1. PAUSE implementation attempts.
  2. REFLECT: Generate a structured reflection note.

     <<REFLECTION_NOTE>>
     **Problem:** A brief summary of the failing test.
     **Root Cause Analysis:** My hypothesis for why the previous attempts failed.
     **Next Strategy:** A new, alternative approach to solve the problem.
     <</REFLECTION_NOTE>>

  3. SELF-SCORE (R³): Append a self_score: [1-5] to the reflection, rating your confidence in the new strategy. If the score is ≤ 3, you must regenerate the reflection with a different strategy.
  4. LOG: Append the final, high-scoring reflection note to /docs/DECISION_LOG.md.
  5. RETRY: Prepend the reflection note to your next implementation prompt and resume attempts.

Level 3: Competitive Self-Duel (attempts == 5)

• ACTION:
  1. PAUSE all other approaches.
  2. INITIATE DUEL: In a single prompt, instruct yourself to act as two independent expert coders, Coder A (using Strategy A) and Coder B (using Strategy B). Generate two distinct patches for the problem.
  3. SELF-CRITIQUE: After generating both patches, provide a critique of the pros and cons of each.
  4. JUDGE: Select the winning patch based on your critique.
  5. APPLY & LOG: Apply the winning patch and log the entire duel (both patches and the critique) to /docs/DECISION_LOG.md.
  6. RESET & RETRY: Reset the attempts counter to 0 and re-run the tests with the winning patch.

Level 4: Escalation (attempts > 5 or after a failed Duel)

• ACTION:
  1. HALT: Stop all implementation attempts for this task.
  2. BLOCK TASK: Move the task file from /project/tasks/in_progress/ to /project/tasks/blocked/.
  3. REPORT TO HUMAN: Update project_status.md to show the task is blocked. Clearly state the problem, link to the relevant entries in /docs/DECISION_LOG.md, and explicitly ask for human guidance. You may suggest creating a new research task or simplifying the requirement.