proposal-review_skill

Overview

This skill facilitates a methodical review of proposals (technical designs, product specs, feature requests) by chunking content, predicting reviewer reactions, and delivering formatted, actionable feedback. It accepts markdown, GitHub gists/issues/PRs, Google Doc exports, and plain text. The goal is clear, reproducible reviews that map to the proposal's original format.

How this skill works

It reads the entire proposal, detects the source format and structure, then splits the document into 3–8 smart chunks based on headers, length, and topic boundaries. For each chunk it presents the content, predicts 3–4 likely reviewer reactions (clarifications, concerns, approvals, suggestions), and offers concise ask-user questions to capture reviewer choices or custom feedback. After iterating through all chunks it synthesizes themes, infers overall sentiment, and generates an output matching the source format (PR comment, companion feedback file, or structured markdown).

When to use it

• When asked to “review this proposal”, “give feedback on this doc”, or “help me review this RFC”
• When you have a PR, issue, gist, or markdown spec needing structured feedback
• For product specs or technical designs that need reproducible, section-by-section review
• When multiple reviewers should follow the same review pattern
• When you want feedback formatted back into the original source type

Best practices

• Provide the proposal source or link so format detection works reliably
• If the doc is very long, indicate priority sections to focus on
• Allow reviewer selections in the AskUserQuestion prompts for fastest results
• Request suggested next steps after synthesis to get actionable remediation items
• Use quoted lines in follow-up so proposers see exact context behind critiques

Example use cases

• Review a GitHub PR and produce threaded review comments mapped to specific lines
• Read a product spec markdown and generate a companion feedback.md with section-by-section notes
• Help a team review an RFC by predicting common reviewer reactions and collecting inputs
• Audit a technical architecture doc and produce consolidated themes and suggested next steps
• Quickly assess multiple short feature requests by applying the same chunking and feedback loop