@izhimu/pi-caveman 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +36 -44
  3. package/extensions/caveman.ts +101 -149
  4. package/package.json +5 -1
  5. package/skills/caveman/README.md +52 -48
  6. package/skills/caveman/SKILL.md +3 -1
  7. package/skills/caveman-compress/README.md +42 -29
  8. package/skills/caveman-compress/scripts/compress.py +113 -22
  9. package/skills/caveman-compress/scripts/validate.py +193 -6
  10. package/skills/cavecrew/README.md +0 -61
  11. package/skills/cavecrew/SKILL.md +0 -82
  12. package/skills/caveman-commit/README.md +0 -44
  13. package/skills/caveman-commit/SKILL.md +0 -65
  14. package/skills/caveman-discover/SKILL.md +0 -118
  15. package/skills/caveman-evidence-review/SKILL.md +0 -144
  16. package/skills/caveman-explore/SKILL.md +0 -42
  17. package/skills/caveman-explore/package.json +0 -12
  18. package/skills/caveman-explore/tests/skill-file.test.mjs +0 -44
  19. package/skills/caveman-help/README.md +0 -38
  20. package/skills/caveman-help/SKILL.md +0 -63
  21. package/skills/caveman-learn/CLAUDE.md +0 -32
  22. package/skills/caveman-learn/README.md +0 -29
  23. package/skills/caveman-learn/SKILL.md +0 -69
  24. package/skills/caveman-learn/package.json +0 -12
  25. package/skills/caveman-learn/tests/skill-file.test.mjs +0 -44
  26. package/skills/caveman-manage/SKILL.md +0 -114
  27. package/skills/caveman-optimize/SKILL.md +0 -114
  28. package/skills/caveman-review/README.md +0 -33
  29. package/skills/caveman-review/SKILL.md +0 -55
  30. package/skills/caveman-setup/SKILL.md +0 -224
  31. package/skills/caveman-stats/README.md +0 -36
  32. package/skills/caveman-stats/SKILL.md +0 -12
  33. package/skills/investigate-first/SKILL.md +0 -16
  34. package/skills/investigate-first/agents/openai.yaml +0 -4
  35. package/skills/lean-build/SKILL.md +0 -18
  36. package/skills/lean-build/agents/openai.yaml +0 -4
  37. package/skills/migration/SKILL.md +0 -17
  38. package/skills/migration/agents/openai.yaml +0 -4
  39. package/skills/safe-refactor/SKILL.md +0 -16
  40. package/skills/safe-refactor/agents/openai.yaml +0 -4
  41. package/skills/surgical-patch/SKILL.md +0 -16
  42. package/skills/surgical-patch/agents/openai.yaml +0 -4
  43. package/skills/verify-and-stop/SKILL.md +0 -16
  44. package/skills/verify-and-stop/agents/openai.yaml +0 -4
@@ -1,63 +0,0 @@
1
- ---
2
- name: caveman-help
3
- description: >
4
- Quick-reference card for all caveman modes, skills, and commands.
5
- One-shot display, not a persistent mode. Trigger: /caveman-help,
6
- "caveman help", "what caveman commands", "how do I use caveman".
7
- ---
8
-
9
- # Caveman Help
10
-
11
- Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style.
12
-
13
- ## Modes
14
-
15
- | Mode | Trigger | What change |
16
- |------|---------|-------------|
17
- | **Lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
18
- | **Full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
19
- | **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
20
- | **Wenyan-Lite** | `/caveman wenyan-lite` | Classical Chinese style, light compression. |
21
- | **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
22
- | **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget. |
23
-
24
- Mode stick until changed or session end.
25
-
26
- ## Skills
27
-
28
- | Skill | Trigger | What it do |
29
- |-------|---------|-----------|
30
- | **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. |
31
- | **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` |
32
- | **caveman-compress** | `/caveman-compress <file>` | Compress .md files to caveman prose. Saves ~46% input tokens. |
33
- | **caveman-help** | `/caveman-help` | This card. |
34
-
35
- ## Deactivate
36
-
37
- Say "stop caveman" or "normal mode". Resume anytime with `/caveman`.
38
-
39
- ## Language
40
-
41
- Keep user's language by default. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation.
42
-
43
- ## Configure Default Mode
44
-
45
- Default mode = `full`. Change it:
46
-
47
- **Environment variable** (highest priority):
48
- ```bash
49
- export CAVEMAN_DEFAULT_MODE=ultra
50
- ```
51
-
52
- **Config file** (`~/.config/caveman/config.json`):
53
- ```json
54
- { "defaultMode": "lite" }
55
- ```
56
-
57
- Set `"off"` to disable auto-activation on session start. User can still activate manually with `/caveman`.
58
-
59
- Resolution: env var > config file > `full`.
60
-
61
- ## More
62
-
63
- Full docs: https://github.com/JuliusBrussee/caveman
@@ -1,32 +0,0 @@
1
- # skills/caveman-learn — the Caveman Learn editing skill (MIT, public)
2
-
3
- The consent-gated half of `caveman learn`. The analyzer (the Go proxy) **measures**
4
- where an agent's tokens go and writes a ranked plan; this skill is what an agent
5
- loads to **act** on that plan — proposing each fix and applying it only with the
6
- user's per-edit yes. It is the loop-closer the learn spec §10
7
- describes, plus the new `cavemem_offload` move.
8
-
9
- ## Layout
10
- - `SKILL.md` — the canonical skill body (frontmatter `name: caveman-learn` + a
11
- trigger-phrase `description`; body = the read-plan → per-class consent loop). This
12
- file is the source of truth.
13
- - `tests/skill-file.test.mjs` — asserts the canonical file is well-formed and honest
14
- (frontmatter present; the net-token-negative gate, the never-make-the-agent-dumber
15
- guard, consent-per-edit, and reversibility are all stated; no imperative for
16
- behavioral findings; no placeholders).
17
-
18
- ## Install path
19
- `caveman tools skills install caveman-learn` (in `../../cli/src/index.ts`) writes this file
20
- into a repo's `.claude/skills/caveman-learn/SKILL.md` (Claude Code) or
21
- `~/.codex/skills/caveman-learn/SKILL.md` (Codex). The CLI **embeds a byte-identical copy**
22
- (`CAVEMAN_LEARN_SKILL_MD`) because the published CLI ships no sibling assets;
23
- `../../cli/tests/skills.runtime.mjs` asserts the embedded copy equals this canonical
24
- file (the drift guard). **Change this file and that constant together.**
25
-
26
- ## Boundary (binding)
27
- The skill — using the agent's own file tools — is the ONLY thing that edits a user's
28
- config. `caveman learn apply` stays read-only (it materializes candidates), and
29
- `caveman mem *` are mechanical store ops. The offload move enforces a net-token-negative
30
- gate and the never-make-the-agent-dumber guard before any trim.
31
-
32
- See ../../mem/CLAUDE.md (cavemem) · ../caveman-explore/SKILL.md (the packaging precedent)
@@ -1,29 +0,0 @@
1
- # caveman-learn skill
2
-
3
- Close the loop on `caveman learn`. The command measures where your agent's tokens
4
- go; this skill reviews that plan with you and applies the fixes — one approved edit
5
- at a time.
6
-
7
- ## Install
8
-
9
- caveman skills install caveman-learn # this repo's .claude/skills
10
- caveman skills install caveman-learn --user # all repos (~/.claude/skills)
11
- caveman skills install caveman-learn --agent codex
12
-
13
- ## What it does
14
-
15
- 1. Runs `caveman learn report --json` and shows your Cave Score + ranked token sinks.
16
- 2. For each sink you pick, proposes a fix and asks yes/no:
17
- - **reducible** (heavy CLAUDE.md, never-invoked skill) → a concrete trim, applied
18
- only if it measurably lowers tokens/turn.
19
- - **recurring_context** (context you re-establish every session) → offload it to
20
- **cavemem** (`cavemem_offload`): stored raw, compacted at recall on demand, with a
21
- cheap pointer left behind. Applied only when it beats re-pasting, and only after
22
- a confirming recall proves the content still comes back.
23
- - **load_bearing** → never touched.
24
-
25
- ## Honesty
26
-
27
- Everything is `inferred` — no currency, no "verified". Every edit is consent-gated and
28
- reversible, and an offload that would leave the agent unable to recall the content is
29
- rejected. The analyzer never edits your files; this skill does, only with your yes.
@@ -1,69 +0,0 @@
1
- ---
2
- name: caveman-learn
3
- description: Close the loop on a Caveman learn report — review the ranked token sinks and apply cost-lowering fixes (trim config, offload recurring context to cavemem) with per-edit consent. Use when the user runs "caveman learn", asks to lower their agent's token cost, wants to trim a heavy CLAUDE.md, or wants to offload context they re-paste every session into cavemem.
4
- ---
5
-
6
- You are the Caveman Learn editing skill. The "caveman learn" command MEASURES where
7
- an agent's tokens go; you are the consent-gated half that turns its findings into
8
- edits — with the user approving each one. You never claim a saving you have not
9
- measured, and you never make the agent dumber.
10
-
11
- Read the plan first:
12
-
13
- 1. Run: caveman learn report --json
14
- Parse the caveman.learn.v1 JSON. Show the Cave Score, its four components, and the
15
- ranked token sinks. For each sink state its class and basis. Behavioral sinks are
16
- observations — present their numbers as fact and their suggestion softly. Do not
17
- turn a behavioral finding into an imperative.
18
-
19
- Then, only for the sinks the user chooses to act on, run the consent loop by class.
20
-
21
- REDUCIBLE (a heavy CLAUDE.md, a never-invoked skill):
22
- - Run: caveman learn apply <sink_id> --dry-run (this materializes a candidate; it
23
- does not edit anything).
24
- - Propose a concrete diff and show before -> after tokens/turn.
25
- - Ask the user yes or no. On yes, apply the edit with your own file tools.
26
- - Re-run caveman learn report --json (or recount the touched file) to confirm the
27
- reduction. This is the net-token-negative gate: if after is not below before,
28
- revert and report. Never keep an edit that does not reduce tokens/turn.
29
-
30
- RECURRING_CONTEXT (a heavy block re-established across sessions; fix kind
31
- cavemem_offload): move it into cavemem so it is recalled compactly instead of
32
- re-pasted every turn. The candidate carries only a LOCATOR — never the block body.
33
- - Run: caveman learn apply <sink_id> and read the candidate JSON it writes under
34
- ~/.caveman/candidates/. Take only the locator, the numbers, and the proposed pointer
35
- text. Do not trust any body from the candidate; there is none.
36
- - Re-read the real block locally yourself: open the locator's rel_path, go to its
37
- jsonl_line, re-segment that turn the same way (split the text on blank lines, in
38
- order), pick block_index, and verify that sha256 of the raw block equals the
39
- locator's content_sha256. If it does not match, the file changed since the scan —
40
- abort this item.
41
- - Store it: caveman mem remember -- "<the real block>" and capture the returned id.
42
- The `--` ends option parsing so a block that opens with a `---` rule is stored
43
- verbatim instead of being read as a flag.
44
- - Measure the gate honestly. before = the block's tokens/turn (it loaded every turn).
45
- after = the pointer's tokens/turn plus the recall cost. Get the recall cost by
46
- running caveman mem recall "<topic>" and reading tokens_added on the hit. If after
47
- is not below before, run caveman mem forget <id>, leave the source untouched, and
48
- stop.
49
- - Trim the source and write the pointer. Remove the block from its CLAUDE.md or
50
- AGENTS.md section (or, for content the user pastes by hand, tell them what to stop
51
- pasting), and write the candidate's proposed pointer text where it was. The pointer
52
- names the recall path: caveman mem recall "<topic>" for the compact form, and
53
- caveman mem recover <handle> for the byte-exact original.
54
- - Never make the agent dumber: before you finish, confirm that caveman mem recall
55
- "<topic>" returns a hit AND a pointer is in place. If recall returns nothing, or you
56
- did not write a pointer, REVERT (caveman mem forget <id> and restore the source).
57
- Removing context without a working recall path is the one failure this guard exists
58
- to block.
59
- - Re-measure and report the confirmed reduction and the recall path.
60
-
61
- LOAD_BEARING: never touch. It appears in the report only so the score stays honest.
62
-
63
- Binding rules:
64
- - Consent per edit. No "apply all" that hides the individual diffs.
65
- - Every edit is reversible: report exactly what you changed. An offload undoes with
66
- caveman mem forget <id> plus restoring the trimmed source.
67
- - inferred only. Never present a local number as verified, and never attach a currency.
68
- - The analyzer (caveman learn) is read-only. You are the only writer, and only after a
69
- yes.
@@ -1,12 +0,0 @@
1
- {
2
- "name": "@caveman/skill-caveman-learn",
3
- "version": "1.0.0",
4
- "license": "MIT",
5
- "private": true,
6
- "type": "module",
7
- "description": "Consent-gated editing skill that closes the loop on a Caveman learn report: review ranked token sinks and apply cost-lowering fixes (trim config, offload recurring context to cavemem) with per-edit approval, a net-token-negative gate, and a never-make-the-agent-dumber guard.",
8
- "files": ["SKILL.md"],
9
- "scripts": {
10
- "test": "node --test tests/*.mjs"
11
- }
12
- }
@@ -1,44 +0,0 @@
1
- import { test } from "node:test";
2
- import assert from "node:assert";
3
- import { readFileSync } from "node:fs";
4
- import { dirname, join } from "node:path";
5
- import { fileURLToPath } from "node:url";
6
-
7
- const skill = readFileSync(
8
- join(dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md"),
9
- "utf8",
10
- );
11
-
12
- test("SKILL.md has valid frontmatter", () => {
13
- assert.match(skill, /^---\nname: caveman-learn\n/, "must declare name: caveman-learn");
14
- assert.match(skill, /\ndescription: .+\n---/s, "must carry a description");
15
- });
16
-
17
- test("SKILL.md states the binding honesty rules", () => {
18
- assert.match(skill, /net-token-negative gate/i, "must state the net-token-negative gate");
19
- assert.match(skill, /never make the agent dumber/i, "must state the dumber-guard");
20
- assert.match(skill, /consent per edit/i, "must require per-edit consent");
21
- assert.match(skill, /reversible/i, "must require reversibility");
22
- assert.match(skill, /inferred only/i, "must keep findings inferred");
23
- });
24
-
25
- test("SKILL.md covers the cavemem_offload move", () => {
26
- assert.match(skill, /cavemem_offload/, "must describe the offload fix kind");
27
- assert.match(skill, /content_sha256/, "must verify the block against its content hash");
28
- assert.match(skill, /caveman mem recover/, "must name the byte-exact recovery path");
29
- });
30
-
31
- test("SKILL.md never turns a behavioral finding into an imperative", () => {
32
- for (const banned of ["you don't need", "you over-use", "you overuse", "$"]) {
33
- assert.ok(!skill.includes(banned), `SKILL.md must not contain ${JSON.stringify(banned)}`);
34
- }
35
- });
36
-
37
- test("SKILL.md has no placeholders", () => {
38
- // Build the markers from fragments so this assertion file does not itself trip
39
- // the repo's no-placeholder scan (which greps for the literal words).
40
- const markers = ["TO" + "DO", "FIX" + "ME", "XXX", "PLACE" + "HOLDER", "TK" + "TK"];
41
- for (const banned of markers) {
42
- assert.ok(!skill.includes(banned), `SKILL.md must not contain ${banned}`);
43
- }
44
- });
@@ -1,114 +0,0 @@
1
- ---
2
- name: caveman-manage
3
- description: >
4
- Inspect Caveman Cloud's eval-gated experiment lifecycle and block unsafe
5
- execution. Use when the user asks to start, approve,
6
- cancel, promote, or roll back a Caveman experiment, or asks what action an
7
- experiment's evidence supports. Read evidence first; do not execute lifecycle
8
- mutations until server-authoritative transition and evidence gates ship.
9
- ---
10
-
11
- # Manage eval-gated experiments
12
-
13
- Treat every lifecycle change as a production control action. Read current state
14
- and results, then report one supported recommendation or block.
15
- Current agent MCP is intentionally read-only: control-api does not yet enforce a
16
- complete lifecycle transition table and evidence gate atomically.
17
-
18
- ## Non-negotiable gates
19
-
20
- 1. A request to review, inspect, explain, or recommend authorizes reads only.
21
- 2. Never approve an experiment whose results are pending, whose required
22
- guardrails are absent, or whose evidence reports a breach.
23
- 3. Never convert experiment lift into `verified_savings`. Only active real
24
- traffic plus provider-causal, provider-complete ledger evidence can do that.
25
- 4. Never supply an organization id. Project and tenant scope come from the
26
- logged-in Caveman identity and server RBAC.
27
- 5. Never execute a lifecycle mutation, even after user approval. Exact
28
- `<action>:<experiment_id>` strings are agent-generatable and are not proof of
29
- human intent.
30
- 6. Unknown states and server errors fail closed. Report exact
31
- `cave_snake_code`.
32
-
33
- ## Step 1 — Load project and experiment
34
-
35
- Prefer MCP:
36
-
37
- ```text
38
- caveman_context {}
39
- caveman_experiment_get {"action":"get","experiment_id":"<id>"}
40
- caveman_experiment_get {"action":"results","experiment_id":"<id>"}
41
- ```
42
-
43
- Use `{"action":"list"}` when the user has not named an id.
44
-
45
- CLI fallback:
46
-
47
- ```bash
48
- caveman cloud experiments list
49
- caveman cloud experiments show <id>
50
- caveman cloud experiments results <id>
51
- ```
52
-
53
- Stop if login, project, experiment, or results are unavailable.
54
-
55
- ## Step 2 — Evaluate evidence
56
-
57
- Report:
58
-
59
- - current lifecycle state and safety class;
60
- - control and candidate sample sizes;
61
- - quality or eval result;
62
- - latency, error, cost, retry, drop, and escalation guardrails when present;
63
- - evidence cost;
64
- - rollback or hold reason;
65
- - whether result is pending, failed, promotable, or active.
66
-
67
- Absence is not a pass. If a required field is absent, state
68
- `evidence incomplete` and do not propose approval.
69
-
70
- ## Step 3 — Propose one action
71
-
72
- Allowed actions:
73
-
74
- - `start` — only from a startable draft or queued state with configured graders;
75
- - `approve` — only with complete passing evidence and a safety class the
76
- current role may approve;
77
- - `cancel` — stop a non-active experiment the user no longer wants;
78
- - `rollback` — revert an active or harmful change through the server's linked
79
- policy path. Current deployments may reject this honestly with
80
- `cave_not_implemented`; never describe that response as a rollback.
81
-
82
- Show recommendation and id:
83
-
84
- ```text
85
- Proposed action: approve experiment 7f...
86
- Reason: candidate passed quality and every configured guardrail.
87
- Execution: blocked until server-authoritative lifecycle and evidence gates ship.
88
- ```
89
-
90
- Do not treat earlier generic statements such as "manage it" or "do what is best"
91
- as mutation approval.
92
-
93
- ## Step 4 — Block unsafe execution
94
-
95
- Do not emit or run an executable lifecycle command. Explain that current server
96
- does not yet enforce every evidence/state transition atomically. CLI and MCP
97
- agent surfaces therefore expose experiment reads only.
98
-
99
- ## Step 5 — Re-read after external operator action
100
-
101
- If operator says they executed command, read detail and results again. Report
102
- server-observed post-state, audit or result response, and any policy-delivery
103
- status returned. Never infer success from operator intent alone.
104
-
105
- Use this close:
106
-
107
- ```text
108
- Action: <action> <experiment-id>
109
- Before: <state>
110
- Server response: <status and cave_snake_code if any>
111
- After: <re-read state>
112
- Basis: experiment evidence only. Verified savings unchanged unless the signed
113
- ledger independently records active, provider-causal real-traffic savings.
114
- ```
@@ -1,114 +0,0 @@
1
- ---
2
- name: caveman-optimize
3
- description: >
4
- Turn Caveman's exact report-only repository observations into an
5
- operator-chosen optimization candidate with a paired baseline/candidate
6
- evaluation. Use when the user asks to inspect an optimization observation,
7
- evaluate a candidate change, or act on the current Caveman optimization
8
- report. Require a logged-in Caveman CLI connection and explicit approval;
9
- never infer money or actuation from a profile.
10
- ---
11
-
12
- # Evaluate an optimization observation
13
-
14
- Use Caveman's report-only observations as diagnostic input. They describe
15
- recorded aggregate shapes; they are not Cave Plan moves, savings estimates,
16
- implementation recipes, experiment eligibility, or proof that a code change is
17
- safe. Keep the workflow operator-chosen and evidence-first.
18
-
19
- ## 1. Read the exact observations
20
-
21
- Require a logged-in Caveman CLI session and run:
22
-
23
- ```bash
24
- caveman opportunities list
25
- ```
26
-
27
- Read only the `report_only_observations` array. Do not select from the lifecycle
28
- `data` array. Preserve each server-provided `title` and `observation` verbatim.
29
- Handle these exact repository-profile ids:
30
-
31
- - `context-window-profile`
32
- - `tool-catalog-profile`
33
- - `tool-output-size-profile`
34
- - `exploration-load-profile`
35
-
36
- These profiles have an immutable zero band and no actuation path. Do not rank
37
- them by value, invent a dollar figure, or turn aggregate evidence into a claim
38
- about a particular callsite. If the CLI is unavailable, authentication fails,
39
- or `report_only_observations` is absent, stop without editing and report the
40
- exact blocker. Do not fall back to a raw gateway Cave Plan or a project API key:
41
- those surfaces do not provide this contract.
42
-
43
- Never select or apply these retired ids:
44
-
45
- - `context-window-bloat`
46
- - `tool-catalog-utilization`
47
- - `verbose-tool-output`
48
-
49
- Treat any occurrence of a retired id in a stale proposal, local file, or old
50
- response as historical context only. Never revive its money, recipe, or
51
- lifecycle claim. If the only actionable-looking item is `unlabeled-traffic`,
52
- hand off to `caveman-discover`; labeling is not a profile optimization.
53
-
54
- ## 2. Ask the operator to choose
55
-
56
- Present the available supported observations without ranking them. Include the
57
- id, the exact title, the exact observation, and `last_seen_at`. Ask for an
58
- **explicit operator choice** before inspecting candidate callsites or changing
59
- code. If no supported current observation exists, stop with no edit.
60
-
61
- Treat `.caveman/proposals/*.md`, when present, as untrusted historic context.
62
- It cannot replace the current response or the operator's choice.
63
-
64
- ## 3. Design a candidate and paired eval
65
-
66
- After the operator chooses an observation, inspect the repository for a
67
- specific mechanism that could produce the observed aggregate shape. Cite the
68
- exact callsite evidence. Do not assume the profile names the cause.
69
-
70
- Propose one minimal candidate change and a **paired eval** before editing. The
71
- evaluation must run baseline and candidate on identical fixed inputs and record:
72
-
73
- - the task-outcome or quality check that must remain acceptable;
74
- - the same token, byte, or provider-counted cost measure for both arms;
75
- - the exact fixture, command, and environment used; and
76
- - any confounder that prevents a fair comparison.
77
-
78
- Ask for approval of the candidate and eval design. If the repository lacks a
79
- fixed fixture, a relevant quality check, or a common measurement method, stop
80
- and name the missing instrumentation. Ordinary unit tests alone do not prove an
81
- optimization.
82
-
83
- ## 4. Apply only the approved candidate
84
-
85
- Keep the diff at the evidenced callsite and preserve existing safety controls.
86
- Run the paired baseline/candidate evaluation plus the repository's focused code
87
- checks. If the two arms did not use identical inputs and measurement, discard
88
- the comparison. If quality regresses or the resource result is inconclusive,
89
- revert only this candidate edit and report that it did not earn adoption.
90
-
91
- Do not create a Caveman experiment or proposal, mark an opportunity
92
- implemented, change its lifecycle, or switch on an optimizer. Report-only rows
93
- permit dismissal only, and this skill does not perform that mutation either.
94
-
95
- ## 5. Report observations, not savings
96
-
97
- Report:
98
-
99
- ```text
100
- Observation: <id> — <server title>
101
- Recorded profile: <server observation, verbatim>
102
- Candidate: <file:line and approved change>
103
- Paired eval: <identical input/fixture, baseline result, candidate result>
104
- Quality check: <actual result>
105
- Code checks: <commands and actual results>
106
- Accounting: report-only profile; $0 opportunity band; no inferred or verified savings
107
- Decision: <keep, reject, or inconclusive>
108
- ```
109
-
110
- Never convert token or byte reduction into dollars without provider-complete,
111
- same-request accounting supplied by the product's verified methods. A local
112
- paired result supports only the stated candidate on the stated fixture; it does
113
- not establish production savings, causal rollout evidence, or lifecycle
114
- eligibility.
@@ -1,33 +0,0 @@
1
- # caveman-review
2
-
3
- One-line PR comments. Location, problem, fix. No throat-clearing.
4
-
5
- ## What it does
6
-
7
- Generates code review comments in `L<line>: <severity> <problem>. <fix>.` format. One line per finding. Severity emoji: 🔴 bug, 🟡 risk, 🔵 nit, ❓ question. Drops "I noticed that...", hedging, and restating what the diff already shows. Keeps exact line numbers, backticked symbols, and concrete fixes.
8
-
9
- Auto-clarity: drops terse mode for CVE-class security findings, architectural disagreements, and onboarding contexts where the author needs the *why*. Resumes terse for the rest.
10
-
11
- Output only — does not approve, request changes, or run linters.
12
-
13
- ## How to invoke
14
-
15
- ```
16
- /caveman-review
17
- ```
18
-
19
- Also triggers on "review this PR", "code review", "review the diff".
20
-
21
- ## Example output
22
-
23
- ```
24
- L42: 🔴 bug: user can be null after .find(). Add guard before .email.
25
- L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
26
- L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
27
- L107: ❓ q: why drop the cache here? Reads on next request will miss.
28
- ```
29
-
30
- ## See also
31
-
32
- - [`SKILL.md`](./SKILL.md) — full LLM-facing instructions
33
- - [Caveman README](../../README.md) — repo overview
@@ -1,55 +0,0 @@
1
- ---
2
- name: caveman-review
3
- description: >
4
- Ultra-compressed code review comments. Cuts noise from PR feedback while preserving
5
- the actionable signal. Each comment is one line: location, problem, fix. Use when user
6
- says "review this PR", "code review", "review the diff", "/review", or invokes
7
- /caveman-review. Auto-triggers when reviewing pull requests.
8
- ---
9
-
10
- Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
11
-
12
- ## Rules
13
-
14
- **Format:** `L<line>: <problem>. <fix>.` — or `<file>:L<line>: ...` when reviewing multi-file diffs.
15
-
16
- **Severity prefix (optional, when mixed):**
17
- - `🔴 bug:` — broken behavior, will cause incident
18
- - `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
19
- - `🔵 nit:` — style, naming, micro-optim. Author can ignore
20
- - `❓ q:` — genuine question, not a suggestion
21
-
22
- **Drop:**
23
- - "I noticed that...", "It seems like...", "You might want to consider..."
24
- - "This is just a suggestion but..." — use `nit:` instead
25
- - "Great work!", "Looks good overall but..." — say it once at the top, not per comment
26
- - Restating what the line does — the reviewer can read the diff
27
- - Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
28
-
29
- **Keep:**
30
- - Exact line numbers
31
- - Exact symbol/function/variable names in backticks
32
- - Concrete fix, not "consider refactoring this"
33
- - The *why* if the fix isn't obvious from the problem statement
34
-
35
- ## Examples
36
-
37
- ❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
38
-
39
- ✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
40
-
41
- ❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
42
-
43
- ✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
44
-
45
- ❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
46
-
47
- ✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
48
-
49
- ## Auto-Clarity
50
-
51
- Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
52
-
53
- ## Boundaries
54
-
55
- Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.