fallow-review

Name: fallow-review
Author: fallow-rs

103stars7forks

How to install fallow-review?

fallow-rs/fallow-skills/fallow-review

$npx -y skills add fallow-rs/fallow-skills --skill fallow-review

Installs into the current project.

Summary

Review AI-generated or human-written code changes with fallow's graph-grounded review brief. Subtracts deterministic concerns (unused code, complexity, duplication, styling) from the loop, ranks what to look at by blast radius and risk, and surfaces the few consequential structur

Files · 1

View on GitHub

SKILL.md

1	# Fallow Review: graph-grounded code review
2
3	`fallow review` turns a changeset into a deterministic, graph-derived review brief and an agent-contract loop. It answers "where do I look, and what calls actually need human taste?" rather than "will CI block this?" (that is `fallow audit`, which gates). `review` always exits 0, so it is safe to run regardless of verdict.
4
5	The four jobs it does, in order:
6
7	- subtract: dead code, complexity, duplication, and styling for the changed files are reported and kept OUT of the judgment loop, so attention is not spent on what a deterministic check already owns.
8	- focus: changed-file units are ranked by a composite attention score (fan-in/out, risk zone, change shape) with a `review-here` / `not-prioritized` label and a full `deprioritized` escape-hatch list, so nothing is hidden.
9	- structure: the decision surface lifts the handful of consequential STRUCTURAL decisions out of the diff and frames each as a judgment question, capped to a working-memory-sized set, each anchored to a `signal_id` fallow emitted.
10	- direct: the walkthrough guide hands an agent a graph-derived digest, the review direction, a graph-snapshot pin, and the exact judgment schema to return.
11
12	## When to use
13
14	- Reviewing a PR, branch, or diff (AI-generated or human-written) before merge.
15	- After an agent has done work and removed the fallow findings it could; this surfaces what is left for human/agent taste.
16	- Producing inline-reviewable judgments that can flow back to the agent that wrote the code.
17
18	## When NOT to use
19
20	- Gating CI on a pass/fail verdict: use `fallow audit` (it exits non-zero on a fail verdict).
21	- Whole-project health, cleanup, or dead-code reports: use the `fallow` skill.
22
23	## Quick human brief
24
25	```bash
26	# Auto-detect the base (merge-base against the upstream / remote default):
27	fallow review
28
29	# Pin the base, or scope to a precise diff:
30	fallow review --base origin/main
31	git diff --find-renames origin/main...HEAD \| fallow review --base origin/main --diff-stdin
32	```
33
34	The human brief prints the orientation facts, the focus map, and the decision surface ("Decisions to make"). `--format json` emits the full structured envelope (`decisions`, `focus`, `deltas`, `impact_closure`, `partition`, `graph_facts`). `--max-decisions N` tunes the cap (clamped to a small band). `--show-deprioritized` expands what the focus map collapsed.
35
36	## The decision surface
37
38	Each decision is a framed question anchored to a `signal_id` fallow deterministically derived from the graph (a delta key or a coordination-gap key). There are exactly three shippable categories:
39
40	- coupling-boundary: a new cross-zone dependency edge.
41	- public-api-contract: a new exported public-API surface, or a changed contract consumed by modules OUTSIDE this diff (a coordinate-or-confirm signal).
42	- dependency: a new third-party dependency (new maintenance + supply-chain surface).
43
44	A decision may carry `previous_signal_id` when its anchor file was renamed in the change: that is the `signal_id` the same decision would have had at the old path, so a review surface can re-attach a prior reviewer comment across a `git mv`.
45
46	## Eliciting the broader trade-offs (taste ownership)
47
48	The decision surface above is the DETERMINISTIC slice: only the trade-offs fallow can prove from the graph (the three categories). Real architectural trade-offs are broader, abstraction level, error-handling strategy, data-model shape, eager-vs-lazy, state ownership, extensibility-vs-YAGNI, testability, trust boundaries, and none of those are graph-detectable. Surfacing them needs a model reading the diff, not a static pass.
49
50	Run the trade-off elicitation prompt in `references/tradeoff-elicitation.md` over the diff plus the guide. It applies TASTE OWNERSHIP: the model makes each choice legible and frames a genuinely open question; the human decides. It never prescribes the answer (not even via a leading "..., or should you X?"), never blocks. The honesty rails: anchor every trade-off to a line present in the diff (with one sanctioned cross-cutting slot), keep `observed` (neutral fact) /

People who liked this also viewed

6 picks

Type

fallow-review

103stars7forks

View on GitHub

How to install fallow-review?

fallow-rs/fallow-skills/fallow-review

$npx -y skills add fallow-rs/fallow-skills --skill fallow-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Fallow Review: graph-grounded code review
2
3	`fallow review` turns a changeset into a deterministic, graph-derived review brief and an agent-contract loop. It answers "where do I look, and what calls actually need human taste?" rather than "will CI block this?" (that is `fallow audit`, which gates). `review` always exits 0, so it is safe to run regardless of verdict.
4
5	The four jobs it does, in order:
6
7	- subtract: dead code, complexity, duplication, and styling for the changed files are reported and kept OUT of the judgment loop, so attention is not spent on what a deterministic check already owns.
8	- focus: changed-file units are ranked by a composite attention score (fan-in/out, risk zone, change shape) with a `review-here` / `not-prioritized` label and a full `deprioritized` escape-hatch list, so nothing is hidden.
9	- structure: the decision surface lifts the handful of consequential STRUCTURAL decisions out of the diff and frames each as a judgment question, capped to a working-memory-sized set, each anchored to a `signal_id` fallow emitted.
10	- direct: the walkthrough guide hands an agent a graph-derived digest, the review direction, a graph-snapshot pin, and the exact judgment schema to return.
11
12	## When to use
13
14	- Reviewing a PR, branch, or diff (AI-generated or human-written) before merge.
15	- After an agent has done work and removed the fallow findings it could; this surfaces what is left for human/agent taste.
16	- Producing inline-reviewable judgments that can flow back to the agent that wrote the code.
17
18	## When NOT to use
19
20	- Gating CI on a pass/fail verdict: use `fallow audit` (it exits non-zero on a fail verdict).
21	- Whole-project health, cleanup, or dead-code reports: use the `fallow` skill.
22
23	## Quick human brief
24
25	```bash
26	# Auto-detect the base (merge-base against the upstream / remote default):
27	fallow review
28
29	# Pin the base, or scope to a precise diff:
30	fallow review --base origin/main
31	git diff --find-renames origin/main...HEAD \| fallow review --base origin/main --diff-stdin
32	```
33
34	The human brief prints the orientation facts, the focus map, and the decision surface ("Decisions to make"). `--format json` emits the full structured envelope (`decisions`, `focus`, `deltas`, `impact_closure`, `partition`, `graph_facts`). `--max-decisions N` tunes the cap (clamped to a small band). `--show-deprioritized` expands what the focus map collapsed.
35
36	## The decision surface
37
38	Each decision is a framed question anchored to a `signal_id` fallow deterministically derived from the graph (a delta key or a coordination-gap key). There are exactly three shippable categories:
39
40	- coupling-boundary: a new cross-zone dependency edge.
41	- public-api-contract: a new exported public-API surface, or a changed contract consumed by modules OUTSIDE this diff (a coordinate-or-confirm signal).
42	- dependency: a new third-party dependency (new maintenance + supply-chain surface).
43
44	A decision may carry `previous_signal_id` when its anchor file was renamed in the change: that is the `signal_id` the same decision would have had at the old path, so a review surface can re-attach a prior reviewer comment across a `git mv`.
45
46	## Eliciting the broader trade-offs (taste ownership)
47
48	The decision surface above is the DETERMINISTIC slice: only the trade-offs fallow can prove from the graph (the three categories). Real architectural trade-offs are broader, abstraction level, error-handling strategy, data-model shape, eager-vs-lazy, state ownership, extensibility-vs-YAGNI, testability, trust boundaries, and none of those are graph-detectable. Surfacing them needs a model reading the diff, not a static pass.
49
50	Run the trade-off elicitation prompt in `references/tradeoff-elicitation.md` over the diff plus the guide. It applies TASTE OWNERSHIP: the model makes each choice legible and frames a genuinely open question; the human decides. It never prescribes the answer (not even via a leading "..., or should you X?"), never blocks. The honesty rails: anchor every trade-off to a line present in the diff (with one sanctioned cross-cutting slot), keep `observed` (neutral fact) /

People who liked this also viewed

6 picks

Type