create-pathfinder 1.3.0 → 1.4.1

package/CLAUDE.md

@@ -57,6 +57,7 @@ Ask before actions identified in `context/ai-interaction.md`, especially depende
 - `to-specs` — generate context-sized feature specs
 - `load-feature` — prepare one feature for implementation
 - `start-feature` — implement scoped delivery chunks
+- `debug-issue` — diagnose an observed failure to its root cause, apply the smallest justified fix, and verify it
 - `review-feature` — review against requirements, regressions, and standards
 - `complete-feature` — verify and close a feature cleanly
 - `learn-feature` — create an interactive lesson for a completed feature

package/README.md

@@ -23,7 +23,7 @@ Pathfinder is a kit of context files and skills — not a framework. There is no
 | --- | --- |
 | `AGENTS.md`, `CLAUDE.md` | Entry files that tell an agent how to work in the project |
 | `context/` | Project truth — overview, standards, interaction rules, current feature |
-| `skills/` | Nineteen skills covering discovery, specs, delivery, review, and learning |
+| `skills/` | Twenty skills covering discovery, specs, delivery, debugging, review, and learning |
 | `prompts/` | Manual launchers for tools that do not discover local skills |
 | `templates/` | Starting points the project copies when it needs them |
 

package/context/features/example-feature-spec.md

@@ -1,4 +1,8 @@
-# [Feature Name]
+# Example Feature Spec
+
+> A worked example of the shape `to-specs` writes into this folder. Real
+> specs are new files here, titled with the feature's own name; copy
+> `templates/feature-spec.template.md` to start one.
 
 ## Status
 

package/context/project-overview.md

@@ -1,9 +1,10 @@
-# [Project Name] — Project Overview
+# Project Overview
 
 > Describe the product, audience, intended feeling, and reason it should exist.
 
 ## Status
 
+- Project: `[Project Name]`
 - Stage: `[idea / prototype / MVP / production / maintenance]`
 - Repo type: `[new / existing / application / library / service / monorepo / other]`
 - Primary goal: `[success definition]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pathfinder",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Install the Pathfinder AI-assisted, human-in-the-loop workflow kit into a Git repository.",
   "keywords": [
     "pathfinder",

package/prompts/15-debug-issue.md

@@ -0,0 +1,15 @@
+Use `skills/debug-issue/SKILL.md`.
+
+Debug the failure I describe.
+
+Establish expected behavior, actual behavior, and reproduction status before proposing any fix.
+
+Read only the code, logs, tests, and configuration relevant to the failure. Do not refactor unrelated code while the cause is still unknown.
+
+State a small ranked set of hypotheses, then test the cheapest one that meaningfully reduces uncertainty. Change one explanatory variable at a time.
+
+Do not call something the root cause because the symptom disappeared. If the evidence only supports a probable cause or a workaround, say so.
+
+Apply the smallest justified fix, then verify against the original failure and the nearby behavior it could have affected. Remove temporary instrumentation.
+
+Stop and report rather than thrashing when the evidence runs out, the reproduction is too unstable, or the fix would require an architectural, dependency, security, or destructive change I have not approved. Preserve what has already been ruled out.

package/skills/debug-issue/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: debug-issue
+description: Diagnose an observed software failure systematically, identify the root cause with evidence, apply the smallest justified fix, and verify the failure is resolved without introducing regressions.
+---
+
+# Debug Issue
+
+Debug an observed failure by reducing uncertainty before changing code.
+
+The goal is not to try fixes until something works.
+
+The goal is to explain the failure well enough that the smallest correct fix becomes justified.
+
+> Reproduce before repairing.
+
+## When to use
+
+Use Debug Issue when there is a concrete unexpected behavior such as:
+
+* a failing test
+* runtime error
+* broken feature
+* regression
+* incorrect output
+* integration failure
+* environment-specific failure
+* intermittent behavior that needs isolation
+* production or staging behavior that differs from expectation
+
+Do not use it merely because implementation work is difficult.
+
+If the task is planned feature construction, use `start-feature`.
+
+If the goal is reviewing completed implementation for possible defects, use `review-feature`.
+
+If the real question is broad understanding of the repository, use `learn-codebase`.
+
+## Goal
+
+Answer:
+
+> What is failing, why is it failing, and what evidence proves the explanation?
+
+Then apply the smallest justified correction and verify the original failure no longer occurs.
+
+## 1. Establish the failure
+
+Before proposing a fix, define:
+
+* expected behavior
+* actual behavior
+* where the failure occurs
+* how it was observed
+* whether it is reproducible
+* relevant environment or conditions
+* known recent changes when relevant
+
+Prefer the smallest reliable reproduction.
+
+If the failure cannot be reproduced, preserve the available evidence and state that limitation explicitly.
+
+Do not manufacture certainty.
+
+## 2. Inspect before changing
+
+Read only the code, logs, tests, configuration, dependencies, and context relevant to the failure.
+
+Identify the execution path involved.
+
+Do not begin with broad refactoring.
+
+Do not change unrelated code while still determining the cause.
+
+## 3. Form hypotheses
+
+Produce a small ranked set of plausible explanations.
+
+For each hypothesis state:
+
+* why it fits the evidence
+* what evidence would support it
+* what evidence would disprove it
+* the cheapest useful test
+
+Prefer hypotheses that explain all known symptoms rather than only one.
+
+Do not create a long speculative list.
+
+## 4. Test discriminating evidence
+
+Test the cheapest hypothesis that meaningfully reduces uncertainty.
+
+Change one explanatory variable at a time when practical.
+
+Examples:
+
+* inspect a value at the failure boundary
+* run one targeted test
+* compare working and failing environments
+* trace one request
+* check one dependency or configuration assumption
+* temporarily instrument the relevant path
+* isolate one integration
+
+A debugging action should answer a question.
+
+Avoid random edits intended only to "see if it works."
+
+## 5. Identify the root cause
+
+Do not call something the root cause merely because changing it makes the symptom disappear.
+
+A root-cause claim should explain:
+
+* why the failure occurred
+* why it occurred under the observed conditions
+* why the evidence supports this explanation
+* why competing explanations are less likely
+
+If the evidence only supports a workaround or probable cause, say so.
+
+## 6. Choose the smallest justified fix
+
+Once the cause is sufficiently established:
+
+* fix the cause rather than only the visible symptom when practical
+* preserve existing behavior outside the failure
+* avoid unrelated cleanup
+* avoid dependency, architecture, schema, security, or workflow changes without required approval
+* prefer a focused regression test when appropriate
+
+If the correct fix expands beyond the active feature or approval boundary, stop and explain the decision required.
+
+## 7. Verify
+
+Verification must include the original failure.
+
+Where relevant also verify:
+
+* the reproduction now passes
+* nearby behavior still works
+* regression tests pass
+* edge/failure states remain correct
+* temporary instrumentation is removed
+* no unrelated behavior changed
+
+Do not declare success only because the code compiles or one unrelated test passes.
+
+## 8. Stop conditions
+
+Stop and report rather than thrashing when:
+
+* 2–3 grounded hypotheses have been tested without reducing uncertainty
+* necessary evidence or environment access is unavailable
+* reproduction is too unstable to support a safe fix
+* the likely fix requires an unapproved architectural, dependency, security, data, or destructive change
+* the observed behavior conflicts with documented requirements and a human decision is needed
+
+When stopping, preserve what has been ruled out so the next attempt does not restart from zero.
+
+## Output
+
+Return:
+
+### Failure
+
+Expected vs actual behavior and reproduction status.
+
+### Evidence
+
+The relevant observations, logs, tests, or code paths.
+
+### Hypotheses tested
+
+What was tested and what each result ruled in or out.
+
+### Root cause
+
+The established cause, probable cause, or remaining uncertainty.
+
+### Fix
+
+The smallest change made or recommended.
+
+### Verification
+
+How the original failure and relevant regression surface were checked.
+
+### Residual risk
+
+Anything still uncertain or unverified.
+
+### Handoff
+
+If unresolved, state the exact next useful investigation step and what should not be repeated.
+
+## Boundaries
+
+`debug-issue` diagnoses an observed failure.
+
+It does not:
+
+* implement unrelated feature scope
+* perform a general repository review
+* replace `review-feature`
+* replace `complete-feature`
+* silently change architecture or dependencies
+* turn debugging into opportunistic refactoring
+* hide uncertainty behind a successful-looking workaround
+
+## Principles
+
+> Reproduce before repairing.
+
+> A debugging action should answer a question.
+
+> Change one explanatory variable at a time.
+
+> Fixes follow evidence, not guesses.
+
+> A symptom disappearing is not proof of root cause.
+
+> Preserve what has already been ruled out.
+
+> Stop when additional attempts are producing activity instead of information.

package/skills/reflect/SKILL.md

@@ -50,9 +50,9 @@ And:
 
 ---
 
-# Part 1 — Reflect on the work
+## Part 1 — Reflect on the work
 
-## 1. Reconstruct what happened
+### 1. Reconstruct what happened
 
 Review the relevant work and available evidence.
 
@@ -73,7 +73,7 @@ Do not rely on vague recollection when repository evidence is available.
 
 Distinguish what actually happened from what was intended to happen.
 
-## 2. Identify learning signals
+### 2. Identify learning signals
 
 Look specifically for:
 
@@ -96,11 +96,11 @@ Success alone is not evidence that the workflow was good.
 
 Failure alone is not evidence that the workflow must change.
 
-## 3. Separate local knowledge from reusable learning
+### 3. Separate local knowledge from reusable learning
 
 Classify each finding as one of:
 
-### PROJECT
+#### PROJECT
 
 Specific to this repository, stack, business domain, architecture, environment, or team.
 
@@ -113,7 +113,7 @@ Examples:
 * this service must start before another service
 * a framework-specific workaround is required
 
-### WORKFLOW CANDIDATE
+#### WORKFLOW CANDIDATE
 
 Potentially useful across unrelated projects.
 
@@ -125,7 +125,7 @@ Examples:
 * an undocumented dependency should have been discovered during system analysis
 * the agent repeatedly needed human correction for something the workflow could have surfaced earlier
 
-### NOISE
+#### NOISE
 
 Interesting but not useful enough to preserve.
 
@@ -133,7 +133,7 @@ Discard it.
 
 Not every observation deserves memory.
 
-## 4. Test generality
+### 4. Test generality
 
 For every WORKFLOW CANDIDATE ask:
 
@@ -149,7 +149,7 @@ If the lesson fails these tests, keep it project-specific.
 
 Generalize behavior, not technology.
 
-## 5. Check for existing coverage
+### 5. Check for existing coverage
 
 Before proposing anything new, inspect the existing Pathfinder workflow and skills.
 
@@ -169,41 +169,41 @@ Avoid duplicate skills.
 
 Do not respond to every failure by adding another instruction.
 
-## 6. Require evidence
+### 6. Require evidence
 
 Every proposed Pathfinder improvement must include:
 
-### Observation
+#### Observation
 
 What happened?
 
-### Evidence
+#### Evidence
 
 What concrete part of the execution demonstrates it?
 
-### Generalization
+#### Generalization
 
 Why could this recur outside this project?
 
-### Current gap
+#### Current gap
 
 Why does Pathfinder not already handle it?
 
-### Proposed change
+#### Proposed change
 
 What is the smallest change that would address it?
 
-### Risk
+#### Risk
 
 How could this rule become harmful, redundant, overly restrictive, or too specific?
 
-### Validation
+#### Validation
 
 How could future work demonstrate that the improvement actually helped?
 
 Do not promote intuition into workflow policy without evidence.
 
-## 7. Prefer the smallest durable improvement
+### 7. Prefer the smallest durable improvement
 
 Possible outcomes include:
 
@@ -222,7 +222,7 @@ An improvement should remove more uncertainty than complexity it introduces.
 
 ---
 
-# Part 2 — Reflect on Reflect
+## Part 2 — Reflect on Reflect
 
 Reflect is subject to the same evidence standard it applies to Pathfinder.
 
@@ -234,7 +234,7 @@ Its purpose is not to endlessly rewrite Reflect.
 
 Its purpose is to discover whether Reflect systematically failed to do its own job.
 
-## 8. Evaluate reflection quality
+### 8. Evaluate reflection quality
 
 Ask:
 
@@ -255,11 +255,11 @@ Do not search for a self-improvement merely because this section exists.
 
 "No improvement needed" is a valid and desirable result.
 
-## 9. Identify Reflect improvement candidates
+### 9. Identify Reflect improvement candidates
 
 If the reflection process itself demonstrated a meaningful weakness, classify it as:
 
-### REFLECT IMPROVEMENT CANDIDATE
+#### REFLECT IMPROVEMENT CANDIDATE
 
 This classification is reserved for improvements to `reflect/SKILL.md` itself.
 
@@ -267,23 +267,23 @@ Do not use it for general Pathfinder improvements.
 
 For each candidate provide:
 
-### Observed weakness
+#### Observed weakness
 
 What was inadequate about Reflect's behavior or reasoning?
 
-### Evidence
+#### Evidence
 
 What concrete output, omission, human correction, or repeated failure demonstrates the weakness?
 
-### Root cause
+#### Root cause
 
 What part of the current Reflect process allowed the weakness?
 
-### Proposed change
+#### Proposed change
 
 What is the smallest change to `reflect/SKILL.md` that could improve future reflections?
 
-### Regression risk
+#### Regression risk
 
 Could the change make Reflect:
 
@@ -295,7 +295,7 @@ Could the change make Reflect:
 * excessively conservative
 * more expensive in context or execution time
 
-### Validation
+#### Validation
 
 What future behavior would demonstrate that the modification actually improved Reflect?
 
@@ -303,11 +303,11 @@ Do not recursively optimize stylistic preferences, wording preferences, or isola
 
 Self-improvements must materially improve reflection quality.
 
-## 10. Evidence levels for self-improvement
+### 10. Evidence levels for self-improvement
 
 Treat evidence for changes to Reflect according to three levels:
 
-### Level 1 — Incident
+#### Level 1 — Incident
 
 One reflection exposed a plausible weakness.
 
@@ -315,13 +315,13 @@ This may justify an improvement candidate.
 
 It does not establish a general pattern.
 
-### Level 2 — Pattern
+#### Level 2 — Pattern
 
 The same weakness has appeared across multiple reflections or required repeated human correction.
 
 This provides stronger justification for changing Reflect.
 
-### Level 3 — Validation
+#### Level 3 — Validation
 
 A proposed change addresses the weakness and subsequent reflections demonstrate better behavior without obvious regression.
 
@@ -331,7 +331,7 @@ When history is available, prefer patterns over isolated incidents.
 
 Do not fabricate historical evidence.
 
-## 11. Bound the recursion
+### 11. Bound the recursion
 
 Reflect may perform only one self-evaluation pass per invocation.
 
@@ -355,9 +355,9 @@ Recursive improvement should accumulate evidence across executions, not consume
 
 ---
 
-# Promotion rules
+## Promotion rules
 
-## Pathfinder improvements
+### Pathfinder improvements
 
 Reflect proposes.
 
@@ -365,7 +365,7 @@ Humans promote.
 
 Do not silently modify Pathfinder's workflow, AGENTS.md, skills, templates, principles, or other durable guidance unless explicitly asked to implement an accepted recommendation.
 
-## Reflect self-improvements
+### Reflect self-improvements
 
 The same rule applies to Reflect itself.
 
@@ -379,21 +379,21 @@ It raises it.
 
 ---
 
-# Output
+## Output
 
 Return only sections that contain meaningful information.
 
 Do not inflate the output to satisfy the template.
 
-## What happened
+### What happened
 
 A concise reconstruction of the relevant execution.
 
-## What we learned
+### What we learned
 
 The important findings and supporting evidence.
 
-## Classification
+### Classification
 
 For each meaningful finding:
 
@@ -403,13 +403,13 @@ For each meaningful finding:
 
 Omit trivial noise when it adds no value.
 
-## Pathfinder gaps
+### Pathfinder gaps
 
 Only genuine gaps not already covered.
 
 If none exist, say so.
 
-## Recommended changes
+### Recommended changes
 
 Rank recommendations from highest to lowest value.
 
@@ -423,11 +423,11 @@ For each recommendation provide:
 * validation approach
 * confidence
 
-## No-change findings
+### No-change findings
 
 Mention important observations that should not modify Pathfinder and explain why.
 
-## Reflect self-evaluation
+### Reflect self-evaluation
 
 Briefly assess whether this reflection process itself performed adequately.
 
@@ -437,7 +437,7 @@ If no material weakness was discovered, state:
 
 Do not invent one.
 
-## Reflect improvement candidates
+### Reflect improvement candidates
 
 Include this section only when evidence supports changing `reflect/SKILL.md`.
 
@@ -454,7 +454,7 @@ For each candidate provide:
 
 ---
 
-# Principles
+## Principles
 
 > Execution is evidence.
 

package/skills/reverse-engineer/SKILL.md

@@ -183,6 +183,7 @@ Do not silently run or imitate the responsibilities of those skills.
 
 Use only the sections that add value:
 
+```markdown
 # Reverse-Engineering Report
 
 ## Objective
@@ -220,6 +221,7 @@ Complexity, accessibility, performance, maintenance, legal, or fidelity concerns
 ## Recommended Pathfinder Handoff
 
 The appropriate next skill, if any, and why.
+```
 
 ## Rules
 

package/skills/to-specs/SKILL.md

@@ -32,7 +32,7 @@ Split a feature when it mixes several systems, requires a repo-wide mental model
 
 ## Output
 
-Create only the coherent MVP roadmap in `context/features/`, using the example template and project-selected naming/delivery policies.
+Create only the coherent MVP roadmap in `context/features/`, using `templates/feature-spec.template.md` and project-selected naming/delivery policies.
 
 Each spec must include Context Boundary, Delivery Chunks, and Learning Targets.
 

package/templates/project-overview.template.md

@@ -1,9 +1,10 @@
-# [Project Name] — Project Overview
+# Project Overview
 
 > Describe the product, audience, intended feeling, and reason it should exist.
 
 ## Status
 
+- Project: `[Project Name]`
 - Stage: `[idea / prototype / MVP / production / maintenance]`
 - Repo type: `[new / existing / application / library / service / monorepo / other]`
 - Primary goal: `[success definition]`