@izhimu/pi-caveman 0.2.0 → 0.4.0
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.
- package/CHANGELOG.md +68 -0
- package/README.md +60 -74
- package/extensions/caveman.ts +452 -346
- package/package.json +37 -6
- package/skills/caveman/README.md +68 -48
- package/skills/caveman/SKILL.md +57 -56
- package/skills/megacave/README.md +11 -0
- package/skills/megacave/SKILL.md +65 -0
- package/skills/ultracave/README.md +13 -0
- package/skills/ultracave/SKILL.md +63 -0
- package/skills/cavecrew/README.md +0 -61
- package/skills/cavecrew/SKILL.md +0 -82
- package/skills/caveman-commit/README.md +0 -44
- package/skills/caveman-commit/SKILL.md +0 -65
- package/skills/caveman-compress/README.md +0 -163
- package/skills/caveman-compress/SECURITY.md +0 -31
- package/skills/caveman-compress/SKILL.md +0 -111
- package/skills/caveman-compress/scripts/__init__.py +0 -9
- package/skills/caveman-compress/scripts/__main__.py +0 -3
- package/skills/caveman-compress/scripts/benchmark.py +0 -80
- package/skills/caveman-compress/scripts/cli.py +0 -85
- package/skills/caveman-compress/scripts/compress.py +0 -414
- package/skills/caveman-compress/scripts/detect.py +0 -139
- package/skills/caveman-compress/scripts/validate.py +0 -221
- package/skills/caveman-discover/SKILL.md +0 -118
- package/skills/caveman-evidence-review/SKILL.md +0 -144
- package/skills/caveman-explore/SKILL.md +0 -42
- package/skills/caveman-explore/package.json +0 -12
- package/skills/caveman-explore/tests/skill-file.test.mjs +0 -44
- package/skills/caveman-help/README.md +0 -38
- package/skills/caveman-help/SKILL.md +0 -63
- package/skills/caveman-learn/CLAUDE.md +0 -32
- package/skills/caveman-learn/README.md +0 -29
- package/skills/caveman-learn/SKILL.md +0 -69
- package/skills/caveman-learn/package.json +0 -12
- package/skills/caveman-learn/tests/skill-file.test.mjs +0 -44
- package/skills/caveman-manage/SKILL.md +0 -114
- package/skills/caveman-optimize/SKILL.md +0 -114
- package/skills/caveman-review/README.md +0 -33
- package/skills/caveman-review/SKILL.md +0 -55
- package/skills/caveman-setup/SKILL.md +0 -224
- package/skills/caveman-stats/README.md +0 -36
- package/skills/caveman-stats/SKILL.md +0 -12
- package/skills/investigate-first/SKILL.md +0 -16
- package/skills/investigate-first/agents/openai.yaml +0 -4
- package/skills/lean-build/SKILL.md +0 -18
- package/skills/lean-build/agents/openai.yaml +0 -4
- package/skills/migration/SKILL.md +0 -17
- package/skills/migration/agents/openai.yaml +0 -4
- package/skills/safe-refactor/SKILL.md +0 -16
- package/skills/safe-refactor/agents/openai.yaml +0 -4
- package/skills/surgical-patch/SKILL.md +0 -16
- package/skills/surgical-patch/agents/openai.yaml +0 -4
- package/skills/verify-and-stop/SKILL.md +0 -16
- package/skills/verify-and-stop/agents/openai.yaml +0 -4
|
@@ -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.
|