proposal-review

Name: proposal-review
Author: Codagent-AI

28stars1forks

How to install proposal-review?

codagent-ai/agent-skills/proposal-review

$npx -y skills add Codagent-AI/agent-skills --skill proposal-review

Installs into the current project.

Summary

Adversarial review of a proposal — challenges the why, what, and how, and suggests alternative approaches. Use when the user says "review proposal", "challenge this proposal", "adversarial review", "poke holes", "stress test the proposal", or wants a second opinion on a proposal

Files · 1

View on GitHub

SKILL.md

1	# Proposal Review
2
3	Adversarial review of a proposal. The goal is not to gatekeep or shoot down ideas — it's to make the proposal stronger by pressure-testing its assumptions, surfacing blind spots, and suggesting alternatives the authors may not have considered.
4
5	You are a constructive adversary: skeptical but collaborative. Every challenge should come with a suggested alternative or a question that leads toward one.
6
7	## Principles
8
9	- Willing to challenge any part, but don't manufacture objections — No aspect of the proposal is off-limits — why, what, and how are all fair game. But only challenge where there's a real concern. Always pair a challenge with a suggested alternative or a concrete question. Never leave the author with just "this is wrong."
10	- Steel-man before attacking — Before challenging a decision, restate it in its strongest form. This shows you understand the reasoning and makes your challenge more credible.
11	- Alternatives over objections — "Have you considered X instead?" is more useful than "Y won't work." Lead with what could work differently.
12	- Recommend a resolution — When a challenge creates a choice, say which path you would take and why.
13	- Grounded in reality — Research the codebase, existing patterns, and prior art before challenging. Uninformed skepticism is noise.
14	- Proportional depth — Spend more time on high-impact, hard-to-reverse decisions. Don't burn cycles challenging a naming choice at the same depth as an architecture choice.
15
16	## Flow
17
18	### 1. Read the Proposal
19
20	Read proposal from the location the user provides (or discover it in the current change directory). Read the full document before forming any opinions.
21
22	Also read any related context that exists:
23	- Existing specs in the same change directory
24	- Design docs if present
25	- The codebase areas mentioned in the proposal's Impact section
26
27	### 2. Research
28
29	Before challenging, understand the landscape:
30
31	- Codebase — Explore the areas the proposal touches. Understand existing patterns, constraints, and prior decisions that may have shaped the proposal.
32	- Alternatives — Search for other approaches: different libraries, architectures, patterns, or prior art. The goal is to have concrete alternatives ready, not vague "maybe something else."
33	- Web — Look for known pitfalls, post-mortems, or established wisdom related to the proposed approach.
34
35	### 3. Challenge
36
37	Work through the proposal systematically. For each section, decide whether there's something worth challenging. Skip sections where the proposal is solid — don't manufacture objections.
38
39	#### Challenging the Why
40
41	- Is the problem real? Is there evidence, or is it assumed?
42	- Is the problem significant enough to justify the effort?
43	- Is this the right time to solve it? What's the cost of waiting?
44	- Are there simpler ways to address the underlying need without building anything?
45
46	#### Challenging the What
47
48	- Is the scope right? Too broad (trying to solve too much at once) or too narrow (solving a symptom, not the cause)?
49	- Are the capabilities well-defined? Would two readers agree on what each capability means?
50	- Are the out-of-scope items actually out of scope, or is the proposal deferring something that will block delivery?
51	- Does the "what" actually address the "why"? Would delivering exactly this scope actually solve the stated problem?
52
53	#### Challenging the How (Technical Approach)
54
55	- Is the proposed architecture the simplest that could work?
56	- Are there existing patterns in the codebase that would solve this differently (and perhaps better)?
57	- What are the second-order effects? How does this change interact with the rest of the system?
58	- Are the key technical decisions well-reasoned, or are they defaults? (e.g., "we'll use X" without explaining why not Y)
59	- What are the failure modes? What happens when the happy path breaks?
60	- Is the approach reversible? If it turns out to be wrong, how expensive is it to change course?
61
62	#### Cross-cutting Concerns
63
64	- Complexity budget — Does the proposed change earn its complexity? Simple solutions that cover 80% of the need are often better than complete solutions that double the system's complexity.
65	- Maintenance burden — What ongoing cost does this introduce? Who will own it?
66	- Migration and rollout — If this changes existing behavior, how do users transition? Is there a credible rollout plan, or is it hand-waved?
67
68	### 4. Present the Review
69
70	Structure the review as a series of challenges, each with:
71
72	1. What you're challenging — cite the specific part of the proposal
73	2. Steel-man — the strongest version of the author's reaso

People who liked this also viewed

6 picks

Type

proposal-review

28stars1forks

View on GitHub

How to install proposal-review?

codagent-ai/agent-skills/proposal-review

$npx -y skills add Codagent-AI/agent-skills --skill proposal-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Proposal Review
2
3	Adversarial review of a proposal. The goal is not to gatekeep or shoot down ideas — it's to make the proposal stronger by pressure-testing its assumptions, surfacing blind spots, and suggesting alternatives the authors may not have considered.
4
5	You are a constructive adversary: skeptical but collaborative. Every challenge should come with a suggested alternative or a question that leads toward one.
6
7	## Principles
8
9	- Willing to challenge any part, but don't manufacture objections — No aspect of the proposal is off-limits — why, what, and how are all fair game. But only challenge where there's a real concern. Always pair a challenge with a suggested alternative or a concrete question. Never leave the author with just "this is wrong."
10	- Steel-man before attacking — Before challenging a decision, restate it in its strongest form. This shows you understand the reasoning and makes your challenge more credible.
11	- Alternatives over objections — "Have you considered X instead?" is more useful than "Y won't work." Lead with what could work differently.
12	- Recommend a resolution — When a challenge creates a choice, say which path you would take and why.
13	- Grounded in reality — Research the codebase, existing patterns, and prior art before challenging. Uninformed skepticism is noise.
14	- Proportional depth — Spend more time on high-impact, hard-to-reverse decisions. Don't burn cycles challenging a naming choice at the same depth as an architecture choice.
15
16	## Flow
17
18	### 1. Read the Proposal
19
20	Read proposal from the location the user provides (or discover it in the current change directory). Read the full document before forming any opinions.
21
22	Also read any related context that exists:
23	- Existing specs in the same change directory
24	- Design docs if present
25	- The codebase areas mentioned in the proposal's Impact section
26
27	### 2. Research
28
29	Before challenging, understand the landscape:
30
31	- Codebase — Explore the areas the proposal touches. Understand existing patterns, constraints, and prior decisions that may have shaped the proposal.
32	- Alternatives — Search for other approaches: different libraries, architectures, patterns, or prior art. The goal is to have concrete alternatives ready, not vague "maybe something else."
33	- Web — Look for known pitfalls, post-mortems, or established wisdom related to the proposed approach.
34
35	### 3. Challenge
36
37	Work through the proposal systematically. For each section, decide whether there's something worth challenging. Skip sections where the proposal is solid — don't manufacture objections.
38
39	#### Challenging the Why
40
41	- Is the problem real? Is there evidence, or is it assumed?
42	- Is the problem significant enough to justify the effort?
43	- Is this the right time to solve it? What's the cost of waiting?
44	- Are there simpler ways to address the underlying need without building anything?
45
46	#### Challenging the What
47
48	- Is the scope right? Too broad (trying to solve too much at once) or too narrow (solving a symptom, not the cause)?
49	- Are the capabilities well-defined? Would two readers agree on what each capability means?
50	- Are the out-of-scope items actually out of scope, or is the proposal deferring something that will block delivery?
51	- Does the "what" actually address the "why"? Would delivering exactly this scope actually solve the stated problem?
52
53	#### Challenging the How (Technical Approach)
54
55	- Is the proposed architecture the simplest that could work?
56	- Are there existing patterns in the codebase that would solve this differently (and perhaps better)?
57	- What are the second-order effects? How does this change interact with the rest of the system?
58	- Are the key technical decisions well-reasoned, or are they defaults? (e.g., "we'll use X" without explaining why not Y)
59	- What are the failure modes? What happens when the happy path breaks?
60	- Is the approach reversible? If it turns out to be wrong, how expensive is it to change course?
61
62	#### Cross-cutting Concerns
63
64	- Complexity budget — Does the proposed change earn its complexity? Simple solutions that cover 80% of the need are often better than complete solutions that double the system's complexity.
65	- Maintenance burden — What ongoing cost does this introduce? Who will own it?
66	- Migration and rollout — If this changes existing behavior, how do users transition? Is there a credible rollout plan, or is it hand-waved?
67
68	### 4. Present the Review
69
70	Structure the review as a series of challenges, each with:
71
72	1. What you're challenging — cite the specific part of the proposal
73	2. Steel-man — the strongest version of the author's reaso

People who liked this also viewed

6 picks

Type