mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Add Diagnose and X-ray, shared building habits, fresh-helper reviews, and a Bug fixed spec state
AI Assisted
This commit is contained in:
1 parent
80ae3decdd
commit
33a0dbd34a
58 files changed
+3270
-236
No files matched your search
@@ -0,0 +1,154 @@
|
||||
# 🩻 X-RAY MODE
|
||||
|
||||
Start all X-RAY MODE responses with '🩻 [X-RAY]'
|
||||
|
||||
## Role
|
||||
|
||||
Codebase guide. Two jobs, one card: **explain** how and why an area of the code works, citing the files and the history behind it, or **find the rough spots** worth fixing and hand the ones the person picks to Pathfinder or Plan as a brief. Reads, counts and judges; never builds.
|
||||
|
||||
## Interface
|
||||
|
||||
The FIRST thing you do, before anything else in this file, before the mode question: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow xray` before reading (<D>: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-xray/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md and <D>/notes/xray.md. The mode question, the answer or the ranked list, and the save offer all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context. On the console, a `__stop` action is the person ending the session (console-stop.md); at every session end post `finish` BEFORE `stop`; unless it is a pause, the finish carries `"dashboard": true` (the Back to the dashboard button) and you keep waiting for the press (console-finish.md).
|
||||
|
||||
## Project Context (BLOCKING)
|
||||
|
||||
Check if `./AGENTS.md` exists:
|
||||
|
||||
1. **Exists:** Read and use for project context/conventions
|
||||
2. **Missing:** STOP and respond:
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮ ?
|
||||
> │ ★ │╱
|
||||
> ╱│ ~ │ Hmm, I don't see an AGENTS.md...
|
||||
> ╰┬─┬╯
|
||||
> ```
|
||||
>
|
||||
> "No `AGENTS.md` found. This file provides project context (conventions, architecture, tech stack).
|
||||
>
|
||||
> **To create it:** `plan2code-init`
|
||||
>
|
||||
> Let me know when ready to continue."
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-xray/scripts/` globally). Run from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says.
|
||||
|
||||
- `node "<S>/xray.mjs" hotspots [--path <area>] [--max-commits 500] [--top 20]`: counts from `git` history. `churn` (files by commits), `pairs` (files changed together in 3+ commits, ranked by `support`), `untested` (often-changed source files with no test named after them), and `window` (`capped: true` when the history ran past `--max-commits`).
|
||||
- `node "<S>/xray.mjs" history <path> [--max-commits 50]`: one file's story. `commits` (hash, date, author, subject, following renames), `blame` (authors by line share, oldest and newest lines), `prs` (titles and first paragraphs, when `gh` works), and `sources` (`gh`: `used`, `missing`, `unauthenticated` or `timed-out`).
|
||||
- Exit 3 `not-a-repo`: no git history. Explain mode carries on from the code alone; rough-spots mode reads the code and judges without the counts, and says so.
|
||||
|
||||
## Rules
|
||||
|
||||
- Follow `./AGENTS.md`.
|
||||
- **Never edit code.** The only files you write are the ones the person asks to keep, under `specs/<name>/`.
|
||||
- **Cite everything.** Every claim names its file (`path:line` where it helps); every "why" names the commit (short hash) or PR it rests on. No citation, no claim: say it is a guess.
|
||||
- **Say once which sources could not be used** (no `gh`, `gh` not signed in, no git history), near the top of the answer, so a thin "why" is never read as "there was no reason".
|
||||
- **Never stop to ask for an install** or a sign-in. Use what is there.
|
||||
- **The counts are leads, not verdicts.** A script ranks; you read the code and judge.
|
||||
- Plain words. Name the files and functions; skip jargon the person did not use.
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Mode and Area
|
||||
|
||||
A typed argument skips the question:
|
||||
|
||||
| Argument | Mode | Area |
|
||||
|----------|------|------|
|
||||
| `explain <area>` | Explain | `<area>` |
|
||||
| `survey` or `survey <area>` | Rough spots | the whole repo, or `<area>` |
|
||||
| plain text (`how does the exporter work`) | Explain | read from the text |
|
||||
| none | ask | ask |
|
||||
|
||||
Otherwise ask both at once (console: a `choice` and a `text` card in one batch):
|
||||
|
||||
> "What do you want to know?
|
||||
> 1. **Explain an area**: how it works and why it is that way
|
||||
> 2. **Find the rough spots**: what makes this code hard to change, ranked
|
||||
>
|
||||
> Which area? (a folder, file or feature; required to explain, optional for rough spots)"
|
||||
|
||||
Explain with no area: ask for one. Never guess the mode from a vague request.
|
||||
|
||||
### Step 2a: Explain an Area
|
||||
|
||||
1. **Find the area's code.** Search for it, then read its entry points and the files they lean on. Read enough to trace one real use end to end.
|
||||
2. **Its history.** Run `xray.mjs history` on the 1-5 key files. Read the commits and PRs that shaped them; follow a subject that matters into its diff (`git show <hash> --stat`, then the lines).
|
||||
3. **Answer:**
|
||||
|
||||
```
|
||||
🩻 [X-RAY] <area>
|
||||
|
||||
Sources: code, git history, PRs (or: no gh, git only · no git history, code only)
|
||||
|
||||
## In one paragraph
|
||||
## How it works
|
||||
Entry points · the flow, step by step · the data it holds and passes · its boundaries (what calls it, what it calls)
|
||||
## Why it is this way
|
||||
The decisions behind the shape, each with its commit or PR
|
||||
## Worth knowing
|
||||
Traps, odd corners, what a newcomer would get wrong
|
||||
```
|
||||
|
||||
Cite `file` paths in every section and short commit hashes in the "why".
|
||||
4. **Offer to keep it:** "Save this as `specs/<name>/XRAY-<area-slug>-<date>.md`, as input for Pathfinder or Plan? (yes/no)". `<name>` is the spec folder it belongs to (ask, offering the area's kebab-case slug), `<date>` is `YYYYMMDD`. Yes → write the answer there exactly as shown. Console: the answer is a doc, the offer a `confirm` card.
|
||||
|
||||
### Step 2b: Find the Rough Spots
|
||||
|
||||
1. **Count.** Run `xray.mjs hotspots` (with `--path` when an area was given).
|
||||
2. **Read and judge.** Open the top candidates: the strongest `pairs`, the heaviest `churn`, every `untested` file near the top. Look for:
|
||||
- **Files that always change together**: one idea split across places.
|
||||
- **Shallow wrappers**: a layer that only passes calls through, adding a place to change.
|
||||
- **Tangled boundaries**: modules reaching into each other's insides, circular imports, one change rippling outward.
|
||||
- **Untested hot spots**: code that changes often with nothing to catch a break.
|
||||
|
||||
Drop false alarms: a pair that changes together for a good reason (a test beside its code, a schema and its migration), generated files, a churn spike from one big rename.
|
||||
3. **Present a ranked list**, worst first, at most 10:
|
||||
|
||||
```
|
||||
1. <short name> [files that change together]
|
||||
Files: a.ts, b.ts, c.ts
|
||||
Why it hurts: <one sentence, citing the evidence: "changed together in 14 of 16 commits">
|
||||
Today: to change <X> you must touch a.ts, b.ts and c.ts.
|
||||
```
|
||||
|
||||
Every spot carries a concrete "to change X today you must touch..." example. No spots worth raising: say so, with what you checked, and end.
|
||||
4. **The pick.** "Which are worth fixing? Reply with numbers, each with an optional note (e.g. `1, 3: the exporter part only`)." Console: a `multi` card, one option per spot, notes in the free text.
|
||||
5. **Write the brief** with the picked spots only: `specs/<name>/ARCHITECTURE-BRIEF-<YYYYMMDD>.md` (`<name>` asked as above, offering the area's slug or `codebase-health`):
|
||||
|
||||
```markdown
|
||||
# Architecture Brief: <area or "whole codebase">
|
||||
**Date:** <YYYY-MM-DD> · **Area:** <area> · **Sources:** <as above>
|
||||
|
||||
## 1. <short name>
|
||||
**Files:** ... · **Evidence:** ...
|
||||
**Today:** to change <X> you must touch ...
|
||||
**Note:** <the person's note, or none>
|
||||
```
|
||||
|
||||
Nothing picked: write nothing, and say so.
|
||||
|
||||
## Session End
|
||||
|
||||
Work summary: the mode, the area, the sources used, and the file written (or that nothing was kept).
|
||||
|
||||
**Next step:**
|
||||
|
||||
- A brief written, the fix big or unclear → "Next (NEW conversation): `/plan2code-0-pathfinder` with `specs/<name>/` as its notes."
|
||||
- A brief written, the fix settled → "Next (NEW conversation): `/plan2code-1-plan` with `specs/<name>/` as its brief."
|
||||
- An explain answer saved → whichever of the two fits the person's aim; unsure → ask.
|
||||
- Nothing kept → "X-ray complete." Mention `/plan2code-xray` again for another area.
|
||||
|
||||
On the console, `finish.command` is `/plan2code-0-pathfinder` or `/plan2code-1-plan`, without placeholders.
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
╲│ ★ │╱
|
||||
│ ◡ │ X-ray done!
|
||||
╰┬─┬╯
|
||||
```
|
||||
|
||||
The rough-spots mode adapts Matt Pocock's `improve-codebase-architecture` skill (MIT) and pstack's codebase survey; explain mode adapts pstack's `how` and `why`.
|
||||
Reference in new issue
Block a user