/code-solving

name: code-solving
description: |
  Structured coding workflow for non-trivial code work: debug, build features, refactor, optimize, migrate and review code through 7 steps with evidence-based quality gates. Use when user says
  "fix this bug", "debug this", "exception", "stack trace", "crash", "the code is not working",
  "add a feature", "refactor", "clean up this code", "the code is slow", "memory leak",
  "flaky test", "CI is failing", "production is down", "upgrade the dependency", "migrate",
  "review my code", "write tests", "fix the error", "add a new feature", "make it faster",
  "upgrade the library".
  Trivial edits (a typo, a rename, a one-line change with an obvious result) do not need this
  process; just make the change.
  Do NOT use for problems outside the code (business, product, process; use problem-solving-pro)
  or for weighing alternatives such as two designs or libraries (use make-decision).

Goal

Make code changes the way a careful senior engineer does: define done before coding, map the change, work in small verified steps, and prove the result with evidence instead of claiming it.

code-solving

A 7-step method (Define → Decompose → Prioritize → Plan → Execute → Verify → Communicate) applied to 12 task types: debug, feature, refactor, performance, flaky-test, incident, migration, review, test, explain, security and quick-fix. Every step has a **gate**: a concrete piece of evidence that must exist before moving on. The knowledge base has 149 records: debugging techniques, change techniques (feature flags, expand-contract, strangler fig…), testing strategies, design principles, engineering biases, a review checklist, hand-off templates and 44 common error messages across languages with their likely causes. The script also detects the project's own test, lint and build commands.

Prerequisites

Detect the Python command first: `python3 --version 2>/dev/null || python --version`. Use whichever works (`python` on most Windows machines) in every command below. The scripts use only the standard library. If neither works, tell the user that Python 3.9+ is needed and ask before installing anything; do not install it yourself.

---

Running the Scripts

Run every command from the **project root** with the path shown, e.g. `python3 .agents/skills/code-solving/scripts/search.py ...` (the installer adjusts this path for your AI tool). Saved plans are written to the project, never inside the skill folder. Saving again never overwrites files that already exist (they hold your notes); add `--force` to replace them.

Passing the user's text

When the query is the user's own words (a request, an error message, a pasted log), pass it on stdin with `--stdin` instead of quoting it, so quotes, backticks and `$` never reach the shell. Every example below does this.

Use exactly this delimiter, `THINK_BETTER_EOF_7f3a`, quoted as shown:

python3 .agents/skills/code-solving/scripts/search.py --stdin --plan <<'THINK_BETTER_EOF_7f3a'
<the user's text, unchanged>
THINK_BETTER_EOF_7f3a

**Check the text first.** The heredoc ends at the first line that is exactly `THINK_BETTER_EOF_7f3a`; anything after it would run as shell commands. If a line of the user's text is exactly that delimiter, do not use the heredoc: write the text unchanged to a temporary file with your file-editing tool (not the shell), run `python3 .agents/skills/code-solving/scripts/search.py --stdin --plan < <file>`, then delete the file.

In PowerShell (keep `'@` at the start of its line):

$OutputEncoding = [Text.UTF8Encoding]::new()
@'
<the user's text, unchanged>
'@ | python .agents/skills/code-solving/scripts/search.py --stdin --plan

The here-string ends at a line that starts with `'@`. If a line of the user's text starts with `'@`, write the text to a file instead and run `Get-Content -Raw -Encoding UTF8 <file> | python .agents/skills/code-solving/scripts/search.py --stdin --plan`.

---

How to Use This Workflow

**Language:** Respond in English. The scripts' output is in English: show it as it is, and keep commands, flags, file names and option names exactly as written.

If the user has not said what they want done, ask before running anything. Trivial edits (a typo, a rename, a one-line change with an obvious result) do not need the plan: make the change and show the check that proves it.

Step 1: Classify the Task

Pick the type yourself; you understand the request better than keyword matching.

| Type | Use when | |------|----------| | `debug` | Wrong result, error, exception or crash with an unknown cause | | `feature` | Adding behavior that does not exist yet | | `refactor` | Changing structure without changing behavior | | `performance` | Too slow, too much memory, does not scale | | `flaky-test` | A test or CI job fails sometimes or only in CI | | `incident` | Production is broken and users are affected now | | `migration` | Upgrading a dependency or moving code/data to another system or version | | `review` | Assessing a change for defects and risks | | `test` | Writing tests for existing code or raising coverage | | `explain` | Understanding how existing code works, without changing it | | `security` | Fixing a vulnerability, an injection, a leaked secret or a vulnerable dependency | | `quick-fix` | A few-line change with an obvious result (typo, text, config value); the plan keeps only Define, Execute, Verify and Communicate |

Step 2: Generate the Plan (REQUIRED)

python3 .agents/skills/code-solving/scripts/search.py --stdin --plan --type <type> -f markdown <<'THINK_BETTER_EOF_7f3a'
<the user's request, unchanged>
THINK_BETTER_EOF_7f3a

If the user asked to save the work ("save", "step-by-step", "workspace"), run the Step 5 command instead of this one: it prints the same plan.

Omit `--type` to auto-detect (the plan says when it is unsure). The plan contains the 7 steps with task-specific guidance and gates, the project's own check