Skip to content

Pathfinder v1.4.0

Choose a tag to compare

View all tags
@rikilamadrid rikilamadrid released this 11 Aug 21:08
· 43 commits to main since this release
v1.4.0
b1a7207
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Pathfinder has a skill for diagnosing a failure, instead of leaving it to the skill built for planned construction.

npx create-pathfinder@1.4.0

debug-issue

The delivery loop ran specs → load → start → review → complete. A failing test, a runtime error, or a regression fell to start-feature, which is built for planned construction and has no rule against editing until the symptom goes away. debug-issue is the twentieth skill and it owns that case.

It establishes expected behavior, actual behavior, and reproduction status before proposing a fix. It states a small ranked set of hypotheses and tests the cheapest one that meaningfully reduces uncertainty, changing one explanatory variable at a time. Then it applies the smallest justified fix and verifies against the original failure and the nearby behavior that fix could have affected.

Reproduce before repairing.

A symptom disappearing does not count as a root cause. When the evidence only supports a probable cause or a workaround, the skill is required to say so.

It stops instead of thrashing

The failure mode this exists to prevent is an agent making twenty edits and reporting success. debug-issue has explicit stop conditions: when the evidence runs out, when the reproduction is too unstable to learn from, or when the fix would require an architectural, dependency, security, or destructive change the human has not approved. It reports what has been ruled out rather than continuing.

Where it sits

Debugging interrupts the delivery loop rather than living inside it, and the boundary against its neighbours is documented in the README:

debug-issue     = an observed failure needs an explanation
start-feature   = planned construction is difficult
review-feature  = completed implementation needs inspection for defects
learn-codebase  = the real question is understanding the repository

It is for a concrete unexpected behavior — a failing test, runtime error, regression, incorrect output, integration failure, environment-specific or intermittent failure. Not for work that is merely hard.

What a destination project receives

Three files, 241 insertions:

  • skills/debug-issue/SKILL.md
  • prompts/15-debug-issue.md — the manual launcher, for tools that do not discover local skills
  • CLAUDE.md — one line adding the skill to the list an agent reads

Upgrading an existing project

Run npx create-pathfinder@1.4.0 in it. The installer never overwrites, which matters here:

  2 files written
  54 files left untouched because they already exist

You get the skill and its launcher. You do not get the CLAUDE.md change, because your CLAUDE.md already exists and the installer will not touch it. If you want your agent to discover the skill from that list, add the line yourself:

- `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it

Invoking the skill directly works either way:

Use skills/debug-issue/SKILL.md. Debug the failure I describe.

Also included in the repository at this tag, but outside the versioned kit scope

The Astro Starlight documentation site, which reads skills/ and context/ in place. site/ is not copied by create-pathfinder, so under Pathfinder's documented version-scope policy it does not independently require an npm/version bump.

Full changelog: https://github.com/rikilamadrid/pathfinder/blob/v1.4.0/CHANGELOG.md

Assets 2
Loading