skills.rest
praveenvijayan
praveenvijayanCOMMUNITY
Explore all skills by this author →
GitHub

ratchet-plan

Converts work requests into plan markdown files on a rolling GitHub planning PR.

2|Updated Jun 13, 2026
Search Tags:#planning#pull request#git workflow#github#acceptance criteria#issue management#agent delivery
One-click install
npx skills add https://github.com/praveenvijayan/Ratchet --skill ratchet-plan-praveenvijayan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ratchet-plan
Source: https://github.com/praveenvijayan/Ratchet/tree/main/plugin/skills/ratchet-plan
Command: npx skills add https://github.com/praveenvijayan/Ratchet --skill ratchet-plan-praveenvijayan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams using a GitHub-native agent delivery loop need a disciplined way to turn bugs and feature ideas into reviewable issue definitions without letting an agent touch code or create issues directly. This Skill writes plan files and manages one always-open planning PR so humans stay in control of what enters the queue. ## Core Features & Use Cases - Quick report mode: Turn a single reported bug or improvement into one plan/NNNN-slug.md file with testable acceptance criteria. - Full plan mode: Decompose a discussed feature into multiple ordered issue files, encoding dependencies via blocked_by slugs. - Rolling planning PR management: Append to the evergreen ratchet/planning branch and its single open PR, or reset it from main when none exists. - Duplicate detection: Scan existing plan files by meaning before writing, updating or reporting already-tracked work instead of duplicating it. - Use Case: After noticing login fails in your app, invoke the Skill with "google signin broken" to get a prioritized plan file with acceptance criteria pushed to the planning PR, ready for human review and merge. ## Quick Start Ask the agent to run ratchet-plan with a short description of the bug or feature you want planned, then review and merge the planning PR it updates.

Frequently Asked Questions about ratchet-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a bug report into a GitHub issue with an agent?▼

Invoke the Skill with a short description like "google signin broken" and it writes one plan file with frontmatter and testable acceptance criteria onto the ratchet/planning branch. Merging the planning PR to main triggers plan-sync, which creates the actual issue.

How do I plan a multi-issue feature with dependencies in GitHub?▼

Describe the feature and the Skill decomposes it into one plan file per issue, ordered so dependencies precede dependents. Ordering is encoded as blocked_by slugs in frontmatter, since the state machine only reads blocked_by, not prose.

Can the planning agent edit code or create issues directly?▼

No. The Skill only writes plan/*.md files on the ratchet/planning branch and manages the planning PR. It never edits code, never commits to main, and never creates issues directly; issues appear only after a human merges the planning PR.

Why did my planned issue sync as state:draft and never get picked?▼

A plan file without at least one testable acceptance criterion in its ## Acceptance criteria block syncs as state:draft and is never picked up. Each criterion must be a concrete, testable checkbox item, since criteria also serve as the test plan.

How does the Skill avoid creating duplicate GitHub issues?▼

Before writing, it reads the titles and acceptance criteria of all existing plan files on the planning branch and compares by meaning, not wording. Matches are updated in place or reported as already tracked instead of duplicated.

Related Skills

Explore More Software Engineering Skills→
recallnetrecallnet
1

goal-planner

Translate vague ideas into actionable goals and GitHub issues.

Official
Intermediate
ByronWilliamsCPAByronWilliamsCPA

pr-review

Reviews GitHub pull requests with parallel agents and fixes open issues in isolated worktrees.

Official
Advanced
fallow-rsfallow-rs
4.4k

implement

Implements Fallow features and fixes through a phased research, test, and review lifecycle.

Official
Advanced
takuto277takuto277

github-issue-create-from-plan

Create GitHub Issues from an agreed plan with optional HTML artifacts.

Community
Advanced