Pathfinder
Audit an unfamiliar or sprawling codebase into feature flowcharts, surface duplicated architecture, and propose a unified refactor plan with handoffs to make-plan.
Overview
Pathfinder is a journey-wide agent skill that maps features into cited flowcharts, reports duplicated concerns, and proposes unified architecture—usable whenever a solo builder needs to audit structure before committing
Install
npx skills add https://github.com/thedotmack/claude-mem --skill pathfinderWhat is this skill?
- Orchestrator maps codebase into feature-grouped Mermaid flowcharts with file:line node labels
- Subagent contract mandates sources, call sites, diagrams, and confidence gaps
- Emits duplication report and proposed unified flowchart in PATHFINDER-YYYY-MM-DD/
- Hands off per-system /make-plan prompts after synthesis stays with orchestrator
- Explicitly does not write implementation code
- Subagent reporting contract requires 4 mandatory sections per report
- Output directory pattern PATHFINDER-YYYY-MM-DD at repo root
Adoption & trust: 1.4k installs on skills.sh; 81.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You inherit a codebase with overlapping subsystems and no trustworthy map of how features actually connect.
Who is it for?
Solo builders pre-refactor on monoliths or multi-feature repos who want cited diagrams and a single unification proposal before coding.
Skip if: Greenfield apps with no code yet, one-file scripts, or tasks where you only need a quick lint fix without architectural synthesis.
When should I use this skill?
User asks to find the ideal path, unify duplicated systems, audit architecture before a refactor, or produce unified flowcharts with make-plan handoffs.
What do I get? / Deliverables
You get a dated PATHFINDER artifact folder with feature flowcharts, a duplication report, a unified architecture diagram, and /make-plan handoff prompts—then implementation follows those plans.
- PATHFINDER-*/00-features.md feature inventory
- Per-feature Mermaid flowcharts in 01-flowcharts/
- Duplication report and proposed unified flowchart with /make-plan prompts
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Run before a launch refactor to see which payment and auth paths duplicate the same session logic.
Map API and worker features into 01-flowcharts before splitting a monolith service.
Re-audit after incident-driven hotfixes created parallel notification pipelines.
Bound feature scope for an MVP by inventorying what already exists versus net-new modules.
Trace cross-feature flows causing recurring support bugs before automating fixes.
How it compares
Use instead of ad-hoc “draw me architecture” chat when you need enforced subagent citations and structured handoff to make-plan.
Common Questions / FAQ
Who is pathfinder for?
Solo and indie developers using agentic workflows who must understand feature boundaries and duplication before a refactor or major ship milestone.
When should I use pathfinder?
Use it in Ship before review-signoff on refactors, in Build when backend and integrations diverged, in Operate when iterating on production pain, and anytime you need to unify duplicated systems with a proposed flowchart first.
Is pathfinder safe to install?
Review the Security Audits panel on this Prism page; the skill reads repository files broadly and may spawn subagents—treat repo access and any delegated shell permissions according to your agent host policy.
Workflow Chain
Then invoke: make plan
SKILL.md
READMESKILL.md - Pathfinder
# Pathfinder You are an ORCHESTRATOR. Map the codebase into feature-grouped flowcharts, identify duplicated concerns, propose the simplest unified architecture, and hand off per-system plans to `/make-plan`. You do not write implementation code. You produce diagrams, a duplication report, a proposed unified flowchart, and handoff prompts. ## Delegation Model Use subagents for *discovery and extraction* (file reading, flow tracing, grep, diagramming). Keep *synthesis* (deciding feature boundaries, picking unification strategies, final flowchart) with the orchestrator. Reject subagent reports that lack source citations and redeploy. ### Subagent Reporting Contract (MANDATORY) Each subagent response must include: 1. Sources consulted — exact file paths and line ranges read 2. Concrete findings — exact function names, call sites, data flow 3. Mermaid diagram(s) with nodes labeled by `file:line` 4. Confidence note + known gaps ## Output Artifacts All artifacts go in `PATHFINDER-<YYYY-MM-DD>/` at repo root: - `00-features.md` — feature inventory with boundaries - `01-flowcharts/<feature>.md` — one Mermaid flowchart per feature - `02-duplication-report.md` — cross-cutting duplicated concerns with evidence - `03-unified-proposal.md` — proposed unified architecture + Mermaid - `04-handoff-prompts.md` — copy-pasteable `/make-plan` prompts per unified system ## Phases ### Phase 0: Feature Discovery (ALWAYS FIRST) Deploy ONE "Feature Discovery" subagent to: 1. Walk the source tree (not built artifacts) and read top-level README / CLAUDE.md 2. Propose feature boundaries based on directory structure, import graph, and naming 3. Return a flat list of features with: name, entry points (file:line), core files, brief purpose Orchestrator reviews the proposal, adjusts boundaries if needed, writes `00-features.md`. Do NOT fan out until feature boundaries are approved. ### Phase 1: Per-Feature Flowcharts (FAN OUT) Deploy ONE "Flowchart" subagent per feature in parallel. Each receives only its feature's scope. Each must: 1. Trace the feature's primary happy path from entry point to terminal state 2. Identify side effects (DB writes, HTTP calls, file I/O, process spawns) 3. Note error and fallback branches but do not let them dominate the diagram 4. Produce a Mermaid `flowchart TD` with every node labeled `Name<br/>file:line` 5. List external dependencies (other features it calls into) at the bottom Orchestrator writes each flowchart to `01-flowcharts/<feature>.md`. Reject any diagram missing `file:line` labels. ### Phase 2: Duplication Hunt Deploy TWO subagents in parallel: **"Within-Feature Duplication"** subagent: - For each feature, find repeated code/logic patterns inside the feature only - Report only duplications worth consolidating (ignore trivial repetition) **"Cross-Feature Duplication"** subagent: - Compare flowcharts across features for concerns that appear in multiple places - Examples of what to look for: multiple capture paths, parallel queue implementations, duplicated storage/migration code, repeated agent scaffolding, parallel parsing layers - For each duplication, report: (a) the concern, (b) every location with `file:line`, (c) why they diverged, (d) whether the divergence is legitimate specialization or accidental Orchestrator synthesizes both into `02-duplication-report.md`. Every duplication claim must cite ≥2 `file:line` locations. ### Phase 3: Unified Proposal (ORCHESTRATOR) The orchestrator writes `03-unified-proposal.md` itself — do not delegate synthesis. For each duplicated concern from Phase 2 that is NOT legitimate specialization: 1. Propose the simplest