Skip to content

gpsaggese/helpers / .claude/skills/auto_task.create_plan_for_feature

auto_task.create_plan_for_feature

Verified

Break a complex feature into an ordered PR plan, with a spec per complex PR

FileKindSize
SKILL.mdskill md5.7 KB
---
description: Break a complex feature into an ordered PR plan, with a spec per complex PR
model: opus
---

# Goal

- Given a request to implement a complex feature, break it into an ordered sequence
  of small, reviewable PRs
- Write a full spec for each PR complex enough to need one
- Do not implement any code

## Input

- The feature/component description, and optionally an existing plan file to extend

# When to Use This Skill

- Use it when one request needs several independently reviewable changes, and at
  least one has a design decision worth writing down
- If the request fits in one PR, skip to "Write a Spec for a PR" with that PR as the
  whole request

# Workflow

## Understand the Request

- Read the related code and the existing code in the target directory
- If the user references a roadmap file (e.g., `plan.<TOPIC>.md` or
  `docs/04-plan.md` per `.claude/skills/project.rules.md`), read it for the exact PR
  scope
  - Use the plan ids (e.g., `PR_M10`) for the `PR<NUM>` bullets and spec files, per
    `.claude/skills/project.rules.md` section "Name the PRs"
- Read the architecture doc of the target directory, if one exists
- If the problem or solution is unclear, follow `.claude/skills/auto_task.rules.md`
  section "Ask for Clarification Before Executing an Unclear Plan" before
  decomposing

## Decompose into PRs

- Break the feature into an ordered sequence of small, cohesive PRs, each reviewable
  and testable alone
- Prefer PRs that change whole files over splitting one file's logic across PRs
- State each PR's dependencies explicitly
- Merge low-risk, low-complexity PRs instead of over-fragmenting

## Decide Which PRs Need a Full Spec

- A PR needs a full spec if it adds a new interface (class, function, CLI flag),
  makes a non-obvious design decision, or carries meaningful risk (shared/core code,
  hard to reverse, many call sites)
- Small, mechanical, low-risk PRs (rename, config tweak, adding a test) need no
  spec: the plan bullet is enough
- For each PR that needs a spec, write it with "Write a Spec for a PR" below, using
  `<TOPIC>_PR<NUM>` as the topic and the plan file below
  - This produces `spec.<TOPIC>_PR<NUM>.md`

## Write a Spec for a PR

- Create a markdown document following `.claude/templates/specs.template.md`
- Follow `.claude/skills/markdown.rules.md` and `.claude/skills/text.rules.md`
- Save it as `spec.<TOPIC>.md` in the current directory
  - E.g., to spec `PR_P2b` from `plan.md`, save `spec.PR_P2b.md`
  - In a project `docs/` dir, add the slot number: save `06-spec.PR_P2b.md` and read
    `04-plan.md`, per `.claude/skills/project.rules.md` section "Name the Docs with
    a Slot Number"
  - Do not name it `plan.<TOPIC>.md`: that name is reserved for the roadmap
- Describe the architecture only. Do not implement any code
  - Short illustrative snippets (interface, schema, signature) are fine
- Distinguish facts (from reading existing code) from decisions
- Reference actual file, class, and function names, not generic paraphrases
- Keep the spec under 100 lines, wrapped at 85 characters
- Update the architecture file, if one exists, per
  `.claude/skills/readme_file.write_architecture/SKILL.md`
  - Add only what shows how the pieces work together, not how the new component
    works internally

## Write the Plan

- Create or update the plan file (e.g. `tasks.md`, or `05-tasks.md` in a project's
  `docs/` dir) following `.claude/templates/auto_task.template.md`
- Fill in the `* Repo:` checklist per `.claude/skills/auto_task.rules.md` section
  "Multi-Repo Issues, Branches, and PRs"
- For each `PR<NUM>` bullet, link its spec when one was written:
  `- [ ] PR<NUM>: <Goal> (see spec.<TOPIC>_PR<NUM>.md)`
- Write bullets per `.claude/skills/markdown.rules.md` and
  `.claude/skills/text.rules.md`, with minimal text
- Do not change any code: only propose the plan and specs

## Rank the PRs

- Order by dependency first: a PR never precedes a PR it depends on
- Among independent PRs, order by increasing complexity, starting with the highest
  design confidence

# Conventions

- Follow `.claude/skills/auto_task.rules.md` for plan format, task list format, and
  issue/branch/PR naming
- Follow `.claude/skills/architecture.rules.md` for layering and interface design
- Follow `.claude/skills/coding.rules.md` and `.claude/skills/testing.rules.md` for
  illustrative snippets
- Say in each spec file how it was generated, right after the title:
  ```markdown
  - Generated by `.claude/skills/auto_task.create_plan_for_feature/SKILL.md`
  ```
- Say in the plan file how it was generated, at the top of the file:
  ```markdown
  <!-- Generated by `.claude/skills/auto_task.create_plan_for_feature/SKILL.md` -->
  ```

# Constraints

- Do not implement any code
- Do not create the GitHub issue or branch: the `auto_task.execute_*` skill does
  that later
- Distinguish facts from decisions made while decomposing

# Verification

- [ ] The plan follows `.claude/templates/auto_task.template.md`
- [ ] Every `PR<NUM>` bullet states a standalone goal and explicit dependencies
- [ ] Every complex PR has a linked `spec.<TOPIC>_PR<NUM>.md` (not
      `plan.<TOPIC>.md`)
- [ ] Every spec section in `.claude/templates/specs.template.md` is filled in or
      marked "Not applicable"
- [ ] No spec contains full implementation code, only interfaces/illustrative
      snippets
- [ ] Every spec's architecture doc was updated, if one exists
- [ ] PRs are ordered by dependency, then by decreasing confidence and increasing
      complexity
- [ ] Only the plan and spec files were written; no code was changed
- [ ] Unclear problems or solutions were raised with the user before finalizing
- [ ] Each spec file and the plan file say they were generated by
      `.claude/skills/auto_task.create_plan_for_feature/SKILL.md`
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall