agentleFS
geemusgeemus/hax-yax/.agents/skills/upsert-plan/SKILL.md

upsert-plan

Skill4 starsChanged 6 months agoMITView on GitHub

Creates and updates detailed, structured work plans as GitHub issues. Use when the user wants to plan a feature, bug fix, project, or any body of work — also triggered by "make a plan", "scope out this work", "break down this task", "help me plan", or "create a GitHub issue for this". In update mode (triggered by an issue number or URL), edits the issue in place and posts a change-summary comment. DO NOT TRIGGER when: user asks to create, update, or delete a skill (use upsert-skill instead).

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Agent guidance: If the work touches repo structure, skills, tooling, or conventions documented in agent instruction files (AGENTS.md, …

    line 77
  2. Distinctive:

    After self-review, challenge the scope.

    line 108
  3. Distinctive:

    If a simpler approach would satisfy all acceptance criteria with fewer tasks, switch to it and update the Approach section accordingly.

    line 112
  4. Distinctive:

    Do not remove tasks that self-review identified as missing or necessary.

    line 114
  5. Distinctive:

    Create mode: Create a new GitHub issue with the derived title and plan body.

    line 132
  6. Distinctive:

    Update the issue title and body with the new plan.

    line 135
  7. Very specific:

    Use added, revised, or removed as the label.

    line 144
  8. Very specific:

    Sub-issues: If sub-issue tracking was agreed in step 1, create a child issue for each phase.

    line 146
  9. Distinctive:

    If git remote get-url origin exits non-zero or returns an unparseable URL, Claude will respond:

    line 189

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Upsert Plan

Turns a work description into a structured, executable plan and writes it to a GitHub issue. Asks clarifying questions when needed and presents the plan for review before writing. Supports create mode (new issue) and update mode (edits an existing issue in place).

Instructions

1. Gather inputs

Collect the following (ask only for what is missing):

  • Work description — what needs to be done (required; may be provided inline as skill args). If the description is too vague to decompose into concrete tasks without guessing, ask 1–2 targeted clarifying questions before continuing.
  • Existing issue target — if the inline args contain a bare integer (e.g. 35), a #N reference (e.g. #35), or a full GitHub issue URL (e.g. https://github.com/owner/repo/issues/35), extract the issue number (and repo from the URL if present). This activates update mode; otherwise the skill runs in create mode.
  • Sub-issues — if the work description clearly involves multiple distinct phases or bodies of work, ask now whether the user wants each phase tracked as a separate sub-issue linked to a parent.

2. Survey the context

Before planning, ground the plan in reality. For a clearly simple task (a single isolated change with no cross-cutting concerns), a lightweight survey — checking only the immediately relevant directory and any context files — is sufficient; skip the open issues/PRs search. For multi-phase or cross-cutting work, run the full survey below.

  • Existing issue content (update mode only): Fetch the current title and body of the target issue to use as planning context and to compute a change summary later.
  • Codebase scan: Use Glob to map the directory structure around the relevant area. Use Grep to search for key terms from the work description. Check for context files (all optional): CLAUDE.md, README.md, AGENTS.md. Read any that exist for conventions and constraints; if absent, proceed without them.
  • Open issues / PRs (skip for simple tasks): Search for open issues and pull requests in the repo matching <keyword>, where the keyword is a specific noun or action from the work description that would appear in issue titles. If no issues or PRs exist yet, note the absence and continue.
  • Best practices search (skip for simple tasks): Form a concise search query by extracting the primary technology or action noun from the work description and appending "best practices" (e.g., "add rate limiting to the API" → "API rate limiting best practices"; "postgres connection pooling" → "postgres connection pooling best practices"). Run one to two targeted WebSearch queries. Summarize any relevant findings in the Background section. If a finding changes the preferred approach, update the Approach section accordingly. Surface any new unchecked assumptions in the Assumptions section.
  • Constraints: Note tech stack, dependencies, CI requirements, and anything that restricts the approach.
  • Record what already exists and what must be built from scratch — this feeds the Background section.

3. Consider approaches

For non-trivial design decisions, briefly evaluate 2–3 alternative approaches. For each, note the key tradeoff. Select the best approach and document the rationale. This becomes the Approach section. Skip this step only when the work involves fewer than 3 tasks and there is clearly no meaningful choice between approaches.

4. Generate the plan

Produce a plan with these sections:

Objective

One or two sentences stating the goal and why it matters.

Background

What exists today, what the context survey found, why this work is needed, and any constraints.

Approach

The chosen approach and why it was selected over alternatives. One short paragraph; include the key tradeoff.

Assumptions

Explicit statements the plan depends on being true (e.g. "The existing auth middleware can be reused", "No breaking API changes are needed"). Flag anything that, if wrong, would require replanning. Omit this section if there are none.

Tasks

Ordered, actionable tasks as GitHub Markdown checkboxes. For non-trivial work, group into phases. Each task should have a single, clear deliverable.

Annotate dependencies explicitly:

- [ ] Task A — no dependencies
- [ ] Task B — no dependencies
- [ ] Task C _(depends on: Task A)_
  - [ ] Sub-task
- [ ] Task D _(depends on: Task B, Task C)_

Mark tasks that can run in parallel with a note: (parallel with: Task X).

Agent guidance: If the work touches repo structure, skills, tooling, or conventions documented in agent instruction files (AGENTS.md, CLAUDE.md), include a final task to run upsert-agents-md to keep those files current.

Update mode: preserve the checked/unchecked state of any task checkboxes that appear in the existing issue. Do not uncheck tasks that were already checked.

Acceptance Criteria

A bulleted list of pass/fail conditions. Each criterion must be verifiable. Pair each with the exact command or action used to verify it:

- All existing tests pass: `npm test`
- Rate limit headers present on API responses: `curl -I /api/... | grep X-RateLimit`

Future Work

Items intentionally deferred: tasks that are nice to have but not required by the acceptance criteria, or that can wait until after launch. Use a bulleted list. Omit this section if there are none.

Open Questions

Unknowns that need resolution before or during the work. Distinct from Assumptions: these are things the plan genuinely cannot answer yet. Omit this section if there are none.

5. Self-review before presenting

Evaluate the draft plan against these checks. Fix any issues found silently before presenting to the user.

  • Does every task have a clear, actionable description? (If not, rewrite vague tasks.)
  • Are dependencies complete and correct?
  • Does the acceptance criteria cover the full objective?
  • Are any assumptions likely to be wrong?
  • Is the plan appropriately scoped — neither too coarse nor too granular?
  • Is the Approach section present and does it name the chosen approach, the reason it was selected, and its key tradeoff?

6. Simplify the plan

After self-review, challenge the scope. Ask: is there a simpler way to achieve the same objective? Make changes silently before presenting.

  • Move any task that is nice to have (not required by the acceptance criteria) or that could be deferred post-launch into the Future Work section. Do not list these as Open Questions. Do not ask the user first.
  • Collapse phases that have no meaningful dependency boundary between them.
  • If a simpler approach would satisfy all acceptance criteria with fewer tasks, switch to it and update the Approach section accordingly.

Do not remove tasks that self-review identified as missing or necessary.

7. Review plan

Invoke the review-plan skill on the current plan draft. review-plan will automatically fix all actionable findings. When review-plan returns, immediately continue to step 8 — do not stop or wait for user input.

8. Refine prose

Invoke the refine-prose skill (/refine-prose) on the full plan draft. Run it silently and carry the refined text forward — do not present the pre-refinement draft. When refine-prose returns, immediately continue to step 9 — do not stop or wait for user input.

9. Present the plan

State whether you are in create mode (a new issue will be created) or update mode (issue #N will be updated in place). Present the finished plan to the user and ask for confirmation before proceeding.

10. Create or update the GitHub issue

Derive the issue title from the Objective: use a concise phrase (under 72 characters) that captures the core action and subject (e.g. "Add rate limiting to the public API").

Create mode: Create a new GitHub issue with the derived title and plan body.

Update mode:

  1. Update the issue title and body with the new plan.
  2. Compose a change-summary comment covering only sections that changed. Format each changed section as a conventional comment in a lettered list:

    a. revised: Tasks — collapsed Phase 2 into Phase 1; no meaningful dependency boundary between them
    b. added: Future Work — deferred dark mode support to post-launch
    c. removed: Open Questions — all questions resolved by codebase survey

    Use added, revised, or removed as the label; write the subject as <Section name> — <one-sentence description of what changed and why>. Post it as a comment on the issue.

Sub-issues: If sub-issue tracking was agreed in step 1, create a child issue for each phase. Link each child to the parent by adding a line to the parent issue body: - Sub-issue: #<number> — <phase name>.

Side effect: creating sub-issues also modifies the parent issue body to add Sub-issue: #<number> reference lines.

11. Report back

Share the issue URL, state the number of tasks and phases, and call out any open questions or high-risk assumptions that should be resolved early. In update mode, confirm that the change-summary comment was posted.

Examples

Invocation (inline description):

/upsert-plan Add rate limiting to the public API

Invocation (interactive):

/upsert-plan

Claude will ask for the work description. Repository is inferred from git remote get-url origin.

Invocation (by issue number — update mode):

/upsert-plan #35

Fetches issue #35, generates an updated plan, edits the issue in place, and posts a change-summary comment.

Invocation (by issue URL — update mode):

/upsert-plan https://github.com/geemus/hax-yax/issues/35

Same as above; repo is extracted from the URL.

Invocation (sub-issues):

/upsert-plan Build new onboarding flow with separate sub-issues for each phase

Claude will ask whether to track each phase as a sub-issue. If confirmed, creates a parent issue and one child issue per phase, then adds Sub-issue: #<number> lines to the parent body.

Invocation failure — git remote unresolvable:

/upsert-plan Add dark mode support

If git remote get-url origin exits non-zero or returns an unparseable URL, Claude will respond:

"Could not infer the GitHub repository from git remote. Please provide the repository in owner/repo format."

Generated issue body structure:

## Objective
...

## Background
...

## Approach
We will use approach X because it minimizes Y; the key tradeoff is Z.

## Tasks

### Phase 1 — Research
- [ ] Task A
- [ ] Task B _(parallel with: Task A)_

### Phase 2 — Implementation
- [ ] Task C _(depends on: Task A)_
  - [ ] Sub-task

### Phase 3 — Validation
- [ ] Task D _(depends on: Task C)_

## Acceptance Criteria
- All tests pass: `npm test`
- ...

## Future Work
- Possible extension: ...

## Open Questions
- ...

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.