repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: design modernize prompt

6f4d1d6402606b4e8047713423e70f0ab038b0cf

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/specs/2026-07-13-modernize-prompt-design.md

Added
new file mode 100644
1 +# Modernize Prompt Design
3 +## Goal
5 +Add project-local `/modernize` guidance that checks this repository against the latest published Pi release and reports every required code migration.
7 +The audit is read-only.
8 +It never edits repository files.
10 +## Entry point
12 +`.pi/prompts/modernize.md` registers `/modernize [focus]`.
14 +The prompt requires the project-local `modernize` skill and passes optional arguments as scan focus without narrowing the mandatory whole-repository audit.
16 +## Components
18 +### Prompt
20 +The prompt defines the user contract:
22 +- run the deterministic preflight first;
23 +- stop if installed Pi is not the latest published Pi;
24 +- normalize changelog candidates against current documentation and runtime source;
25 +- scan every Git-tracked and non-ignored untracked repository file;
26 +- report findings with evidence;
27 +- print funny ASCII art only when no migration is required.
29 +### Skill
31 +`.pi/skills/modernize/SKILL.md` owns the audit procedure.
33 +It separates evidence gathering from semantic judgment:
35 +1. collect versions and changelog candidates with the script;
36 +2. read current Pi docs/source for every relevant candidate;
37 +3. derive concrete obsolete and replacement code shapes;
38 +4. search the repository;
39 +5. inspect every match in context;
40 +6. report confirmed migrations only.
42 +Provider catalog changes, bug fixes, and prose-only changes are excluded unless repository code directly depends on the changed behavior.
44 +### Script
46 +`.pi/skills/modernize/scripts/audit.mjs` uses Node standard library only.
48 +It:
50 +- runs `pi --version`;
51 +- queries the npm registry for the latest `@earendil-works/pi-coding-agent` version;
52 +- fails nonzero when the installed Pi version differs;
53 +- locates the installed Pi distribution changelog;
54 +- fetches the canonical remote changelog pinned to the latest release tag;
55 +- reads repo-resolved `@earendil-works/pi-*` package versions from `package-lock.json`;
56 +- parses version sections;
57 +- extracts migration candidates from Breaking Changes, Changed, Removed, and Deprecated sections plus migration-keyword bullets;
58 +- lists Git-tracked and non-ignored untracked files for the semantic scan;
59 +- emits one JSON object to stdout and diagnostics to stderr;
60 +- writes no files.
62 +The installed CLI is the authoritative “local Pi” for the required latest-version gate.
63 +Older repo-resolved SDK packages are evidence for the migration interval, not a preflight failure by themselves.
65 +## Candidate normalization
67 +Changelog extraction is deliberately over-inclusive.
68 +The skill must confirm each candidate against the latest installed or fetched documentation and runtime declarations before scanning.
70 +Normalization records:
72 +- affected API or behavior;
73 +- obsolete code shape;
74 +- latest replacement shape;
75 +- applicable version interval;
76 +- source changelog entry;
77 +- confirming current doc or source path.
79 +A changelog sentence alone cannot produce a finding.
80 +A repository match alone cannot produce a finding.
81 +Both migration evidence and contextual code evidence are required.
83 +## Repository scan
85 +The script obtains the file set with Git rather than recursive filesystem traversal.
86 +This includes tracked files and non-ignored untracked files while excluding `.git`, ignored caches, dependencies, and generated outputs.
88 +The skill searches all candidate shapes across that file set, then reads each match and its callers before deciding whether migration is required.
89 +Binary files are skipped.
90 +Optional `/modernize` arguments prioritize additional focus but never reduce the full scan.
92 +## Output
94 +Stale local Pi or unavailable version/changelog evidence:
96 +```text
97 +MODERNIZE FAILED
98 +reason: ...
99 +local: ...
100 +latest: ...
101 +```
103 +Confirmed migrations:
105 +```text
106 +MODERNIZE FINDINGS: N
107 +- [severity] path:line — obsolete API or behavior
108 + latest: replacement
109 + evidence: changelog version + current documentation/source
110 +```
112 +No confirmed migrations:
114 +```text
115 +MODERNIZE CLEAN
116 +<funny ASCII art generated for the run>
117 +```
119 +The clean art must not use a box and must remain under 20 lines.
121 +## Failure handling
123 +The audit fails instead of guessing when:
125 +- `pi` is unavailable;
126 +- npm registry lookup fails;
127 +- installed Pi is not latest;
128 +- the canonical latest changelog cannot be fetched;
129 +- changelog parsing yields no release sections;
130 +- Git cannot enumerate the repository.
132 +A failed preflight produces no clean verdict and no celebratory art.
134 +## Verification
136 +Permanent Node tests use fixture changelogs and injected version/source inputs to verify:
138 +- latest-version success;
139 +- stale-version failure;
140 +- candidate extraction by section and keyword;
141 +- ordinary release notes exclusion;
142 +- version ordering;
143 +- malformed changelog failure.
145 +Experimental verification runs real `/modernize` in this repository with current network and Pi installation.
146 +Evidence must show:
148 +- project prompt and skill discovery;
149 +- successful latest-version preflight;
150 +- remote and installed changelog provenance;
151 +- repository scan completion;
152 +- either evidence-backed findings or the clean ASCII-art path.
154 +Temporary experiment artifacts live outside the repository and are deleted afterward.