unstuck

Unstuck

Break out of unproductive loops. Articulate the problem, then either solve it through clarity or escalate systematically.

Step 0.5's iron-law framing + multi-component instrumentation pattern adapted from obra/superpowers/skills/systematic-debugging under MIT.

Step 0: Memory-first

Before asking the user anything, check project memory for prior similar problems:

1. Read MEMORY.md index, scan descriptions for matches against the current symptom (error message, stack trace, behavior)
2. For any matches, read the full memory entry
3. If a strong match exists, present it: "We've hit something like this before: . Is this the same problem? If yes, the prior fix was: ."

If the user confirms it's the same problem, jump straight to Step 5 (Solution Capture) — the entry confirms the user already had the answer.

If no match or user says it's different, proceed to Step 0.5.

Memory format follows the project-memory schema — kebab-case slug + YAML frontmatter (name / description / type).

Step 0.5: Gather evidence

Iron law: no fix proposals without root-cause investigation first. Symptom-fixes mask underlying issues and create new bugs. This step is for the AGENT to do legwork BEFORE asking the human articulation questions — so Step 1's discussion is grounded in facts, not memory of facts.

1. Read the actual error message in full.

   • Don't paraphrase. Copy the literal stack trace, exit code, log line.
   • Note line numbers, file paths, error codes — the message often contains the exact answer.
   • If the error was N invocations ago and you don't have it, ask the user to re-run with the failure reproduced.

2. Check recent changes.

   • git log --oneline -10 on suspect files
   • git diff against last known good
   • New dependencies, config edits, env-var changes
   • The cause is usually in the most recent change, but the SYMPTOM may surface later.