Code Solving

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.

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 commands, techniques, testing strategy, design principles, bias warnings, a review checklist and the hand-off template.

The plan opens with Context from the project: facts the script found in the code and git, so Step 2 starts from them instead of a blank search. Pass the user's full error output and stack trace in the request; the script reads it.

Reviews include the diff automatically: uncommitted changes if there are any, else the branch against the default branch, else the last commit. Name a base with --diff <base> (a branch, tag or commit). Skip all lookups with --no-context. To see only the context, run --stdin --context with the user's text in the same heredoc.

Treat the context as leads to verify, not conclusions: read the code at each location before relying on it.

When the request contains a known error message (for example Cannot read properties of undefined, nil pointer dereference, ModuleNotFoundError), the plan adds a Known error section with its meaning, likely causes, what to check first and the root-cause fix. The likely causes pre-fill the hypothesis log of a saved workspace.

Depth: --depth quick (Define, Execute, Verify only), standard (default), deep (pitfalls per step, extra techniques, full review checklist), executive (deep plus a stakeholder summary).

To see only the project's commands: python3 .agents/skills/code-solving/scripts/search.py --detect

Step 3: Work the Steps, Gate by Gate

Go through the steps in order and keep the user informed in short updates. For each step:

1. Do the step using the task-specific guidance in the plan.
2. Produce the gate's evidence for real: run the repro, run the tests, read the code.
3. Show the evidence briefly (the command and the relevant output lines), then move on.

Never claim a gate is met without having produced its evidence in this session. If a command cannot run (missing tool, no network, no test suite), say so plainly and say what you did instead.

For small tasks, keep the steps light, but do not drop Define and Verify.