UNPKG

paqad-ai

Version:

Spec-driven development framework — AI agents that think before they type

github.com/Eliyce/paqad-ai

Eliyce/paqad-ai

60 lines (43 loc) • 3.59 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
--- name: performance-regression-estimator description: 'Finds performance hazards in a proposed solution before code is written, by severity and hot-path placement. Use when a graduated or full lane change touches data access, request handlers, scheduled jobs or a stated latency or throughput need.' metadata: model_tier: reasoning cacheable: 'false' output_format: markdown paqad-meta: skill.meta.yaml --- ## What It Does Reads a proposed implementation outline and the changed files, scans for known performance hazards (N+1 queries, sync-in-async, missing pagination, suspicious caching, sequential network calls, hot-path logging), and classifies each by severity and hot-path placement. The point is to catch latency and cost regressions during planning, not after a load test or a customer-facing slowdown. ## Use This When In the graduated and full lanes whenever the change touches data access, request handlers, scheduled jobs, or anything with a stated latency or throughput requirement. Skip when the change is purely structural (renames, moves) and exercises no new code paths. ## Inputs - Read the proposed solution at `proposed_solution_path` first. - Read the changed-file list to scope hazards to code that is actually changing. - Read canonical module docs in `module_doc_paths` for declared latency budgets and throughput targets: a hazard on a hot path with a sub-100ms budget is much more severe than the same hazard on a daily batch job. - Read `references/perf-hazards.md` before classifying any hazard so the catalog and severity rubric stay consistent. ## Procedure 1. Enumerate code paths the change introduces/modifies (handlers, jobs, consumers, libs); mark each as hot-path or not based on canonical module docs. 2. Run `scripts/scan-perf-smells.sh <changed-files...>` to surface candidate hazards (N+1, await-in-loop, async-map without Promise.all, deep-clone-via-JSON, log-in-hot-path, unbounded-pagination, cache-without-invalidation, sequential-fetch). 3. Classify each detected hazard using `assets/severity-rubric.txt`: `high` only when on a hot path; `medium` on cold path with unbounded volume; `low` otherwise. 4. For every `high` hazard, propose a concrete remediation tied to the same `file:line`. 5. Format per `assets/output.template.md`; validate with `scripts/lint-output.sh`. ## Output Contract - Return a heading named `Performance Hazards`. - Provide a `Hazard Map` table with columns `#`, `Hazard`, `Path`, `On hot path?`, `Severity`, `Remediation`. - Provide a `Recommended Pre-Merge Actions` ordered list of the `high`-severity hazards' remediations. - Provide an `Open Questions` section listing paths whose hot-path status could not be confirmed from the available docs. - When no hazards are detected, return `Performance Hazards: none detected.` exactly. See `assets/output.template.md` for the canonical shape; `scripts/lint-output.sh` enforces it. ## Escalate / Stop Conditions - Ask when the module's hot-path classification cannot be derived from canonical docs and the proposed solution implies a tight latency budget. - Warn when caching is being added without a documented invalidation rule: recommend either declaring the rule or removing the cache layer. - Do not silence a `high` hazard with phrases like "we'll fix it later": high hazards must either be remediated or explicitly deferred via a Decision Packet. ## Resources - `references/perf-hazards.md` - `scripts/scan-perf-smells.sh` - `scripts/lint-output.sh` - `assets/output.template.md` - `assets/severity-rubric.txt` - `agents/openai.yaml`