agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/make-plan/SKILL.md

make-plan

Skill1 starsChanged 8 months agoMITView on GitHub

Create implementation plans through deep codebase understanding. Use when user asks to create, devise, or write a plan. Leverages subagents to explore approaches, understand systems, and design aligned solutions.

14 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use oh-my-issues, what-the and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • tuliosalustiano27Skill

    oh-my-issues

    Cluster a GitHub issue backlog by root cause into a small set of plan-master issues, redirect children with a standardized comment, and bundle architectural-fix PRs that close clusters atomically. Use when an issue tracker has accumulated dozens of reports that share underlying defects, when asked to triage / consolidate / cluster / dedupe issues, when asked to build a plan series or roadmap from open issues, or when routing a new incoming bug into an existing plan.

    Also in 3 projects that use this

  • tuliosalustiano27Skill

    what-the

    What the? Use when the user wants a plain-English breakdown of something technical — the who, what, where, why, and when.

    Also in 3 projects that use this

  • barrelcSkill

    mem-search

    Search kimi-mneme's persistent cross-session memory database. Use when user asks "did we already solve this?", "how did we do X last time?", "what did we do yesterday?", or needs work from previous sessions.

    Also in 5 projects that use this

  • thedotmackSkill

    pathfinder

    Map a codebase into feature-grouped flowcharts, identify duplicated concerns across features, and propose a unified architecture. Use when asked to "find the ideal path," unify duplicated systems, or audit architecture before a refactor. Emits a proposed unified flowchart plus per-system /make-plan prompts.

    Also in 4 projects that use this

  • dqtx760Skill

    timeline-report

    Generate a "Journey Into [Project]" narrative report analyzing a project's entire development history from claude-mem's timeline. Use when asked for a timeline report, project history analysis, development journey, or full project report.

    Also in 3 projects that use this

  • tunnckoCoreSkill

    how-it-works

    Use for 'how does X work', code walkthroughs before changing something, and placement / ownership / layering questions ('where should this live', 'which package owns this', 'is this the right layer'). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 9 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create focused, actionable implementation plans that recommend the technically best solution.

    line 15
  2. Distinctive:

    Tests exist to validate that code works as intended: When functionality changes, tests SHOULD change.

    line 38
  3. Distinctive:

    Existing code is not sacred: If the existing architecture is flawed, the right answer is to fix it, not preserve it.

    line 42
  4. Distinctive:

    Understand related systems and validate details: - Use subagents to study the architecture, how components work together, their purpose, …

    line 46
  5. Distinctive:

    Explore and design approaches: - Use subagents to investigate different ways to solve the problem.

    line 48
  6. Distinctive:

    Evaluate approaches on technical merit only: - Use subagents to assess each approach.

    line 56
  7. Distinctive:

    Visualize with Architecture Lens: - After finalizing the plan, determine which architecture lens best illustrates the proposed changes, …

    line 64
  8. Very specific:

    Use ● prefix for modified existing components

    line 105
  9. Very specific:

    Use ★ prefix for new components

    line 106
  10. Distinctive:

    Before writing the final plan, verify:

    line 114
  11. Very specific:

    Create files outside temp/make-plan/ directory

    line 139
  12. Very specific:

    Write to temp/make-plan/ directory

    line 143
  13. Very specific:

    If the plan exceeds 500 lines, split it into multiple files (_part_a, _part_b, etc.) at natural section boundaries.

    line 151
  14. Distinctive:

    Never include file paths or guessable names for other parts: No paths, no filenames, no references that allow an agent to locate other part …

    line 154

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “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

Implementation Plan Skill

Create focused, actionable implementation plans that recommend the technically best solution.

When to Use

  • User says "create a plan", "devise a plan", "write a plan"
  • User wants an "implementation plan" for a feature or fix
  • User asks to "plan out" a task or migration

Core Values - CRITICAL

The ONLY criterion for choosing an approach is technical quality and correctness of design. A well-designed system is the goal. Nothing else matters.

NEVER use these as reasons to choose or reject an approach:

  • Implementation effort or difficulty ("would require rewrite" is NOT a reason)
  • Number of files changed
  • Amount of existing code affected
  • Number of tests that would need updating
  • "Migration risk" or "rollback ease"
  • "Preserves existing patterns" (existing patterns may be wrong)
  • "Minimal changes needed"
  • "Zero changes to X" (not a benefit - neutral at best)
  • "Existing tests mostly pass" (tests validate desired behavior, they don't constrain design)

Tests exist to validate that code works as intended. When functionality changes, tests SHOULD change. "Would break tests" is never a reason to reject an approach.

Git handles rollback. Feature flags for rollback are unnecessary complexity.

Existing code is not sacred. If the existing architecture is flawed, the right answer is to fix it, not preserve it.

Planning Steps

  1. Understand related systems and validate details - Use subagents to study the architecture, how components work together, their purpose, patterns, and standards. Validate any details provided in the task description.
  2. Explore and design approaches - Use subagents to investigate different ways to solve the problem. Use subagents with web search to research modern solutions, approaches, designs, and architectures relevant to the problem. For each approach, focus on:
    • Does it solve the problem correctly?
    • Is it the right abstraction?
    • Does it enable future evolution of the system?
    • Is the design clean and understandable?
  3. Design tests first - For the chosen approach, define tests that capture the intended behavior. These tests should fail against the current codebase and pass once the implementation is complete. The implementation steps should be ordered to make these tests pass.
  4. Evaluate approaches on technical merit only - Use subagents to assess each approach. Evaluation criteria:
    • Correctness: Does it fully solve the stated problem?
    • Design quality: Is this the right abstraction? Is it clean?
    • Architectural fit: Does it align with how the system SHOULD work (not how it currently works if current is flawed)?
    • Maintainability: Will future developers understand and extend it?

DO NOT evaluate based on: implementation effort, risk, number of changes, test breakage, or ease of rollback. These are not engineering criteria.

  1. Visualize with Architecture Lens - After finalizing the plan, determine which architecture lens best illustrates the proposed changes, then create a mermaid diagram.

Select the lens based on what the plan primarily affects:

If the plan primarily involves...Use Lens
Adding/modifying containers, services, or integrationsC4 Container
Changing workflow logic, state machines, or decision flowProcess Flow
Altering data storage, transformations, or information flowData Lineage
Restructuring modules, changing dependencies, or layeringModule Dependency
Adding/modifying parallel execution or thread handlingConcurrency
Changing error handling, retry logic, or recovery pathsError/Resilience
Modifying repository patterns or data accessRepository Access
Changing CLI commands, config, or monitoringOperational
Adding/modifying validation, trust boundaries, or isolationSecurity
Changing build tools, test framework, or quality gatesDevelopment
Affecting multiple user journeys or cross-component flowsScenarios
Modifying state contracts, field lifecycles, or resume logicState Lifecycle
Changing deployment topology or infrastructureDeployment

MANDATORY: LOAD the appropriate arch-lens skill using the Skill tool:

LensSkill to LOAD
C4 Container/arch-lens-c4-container
Process Flow/arch-lens-process-flow
Data Lineage/arch-lens-data-lineage
Module Dependency/arch-lens-module-dependency
Concurrency/arch-lens-concurrency
Error/Resilience/arch-lens-error-resilience
Repository Access/arch-lens-repository-access
Operational/arch-lens-operational
Security/arch-lens-security
Development/arch-lens-development
Scenarios/arch-lens-scenarios
State Lifecycle/arch-lens-state-lifecycle
Deployment/arch-lens-deployment

Create the diagram following the loaded skill's instructions:

  • Focus on the PROPOSED changes (use newComponent class for new elements)
  • Show how new components integrate with existing architecture
  • Use ● prefix for modified existing components
  • Use ★ prefix for new components

Include the diagram in the plan document under a "## Proposed Architecture" section. More than one lens diagram is okay if it is complex plan (don't do more than 3, and make sure to load each appropriate skill).

Skill Loading Checklist

Before writing the final plan, verify:

  • Determined which architecture lens best fits the proposed changes
  • LOADED the corresponding /arch-lens-* skill using the Skill tool
  • The arch-lens skill LOADED the /mermaid skill for styling
  • Diagram uses ONLY the classDef styles from the mermaid skill (no invented colors)
  • Diagram includes a color legend table
  • Every new component, class, or function is wired into the call chain — nothing is created but left unconnected

Critical Constraints

NEVER use EnterPlanMode. This skill IS the planning process. Execute the planning steps directly — explore with subagents, design the approach, write the plan file to temp/make-plan/. Do not enter plan mode, do not call ExitPlanMode. Just do the work and deliver the plan.

NEVER include:

  • Multiple alternative approaches (recommend ONE only)
  • Stakeholder sections
  • PR breakdown sections
  • Backward compatibility considerations
  • Fallback mechanisms
  • Justifications based on effort, risk, or preserving existing code

NEVER:

  • Change any code
  • Choose an approach because it's easier
  • Reject an approach because it's harder
  • Create files outside temp/make-plan/ directory
  • Include git cherry-pick or git checkout <branch> -- <file> in plan steps — these bypass the worktree isolation model

ALWAYS:

  • Write to temp/make-plan/ directory
  • Recommend the single best technical solution
  • Ground decisions in design quality and correctness
  • Include verification steps
  • Be willing to recommend significant refactoring if that's the right answer

Output

If the plan exceeds 500 lines, split it into multiple files (_part_a, _part_b, etc.) at natural section boundaries. Use as many parts as needed.

CRITICAL — Multi-part plan rules:

  • Never include file paths or guessable names for other parts. No paths, no filenames, no references that allow an agent to locate other part files.
  • Include only a brief plain-text note about what subsequent parts cover (e.g., "Part B will cover X and Y — implement as a separate task").
  • The title of each part file MUST include — PART A ONLY (or B, C, etc.) so scope is immediately visible.
  • Each part file MUST open with the scope warning block shown in the multi-part template below.

Save the plan to: temp/make-plan/{task_name}_plan_{YYYY-MM-DD_HHMMSS}.md

Plan structure (single-part):

# Implementation Plan: {Task Name}

## Summary
{Brief overview of what will be implemented}

## Proposed Architecture
{Mermaid diagram showing the proposed changes using the selected lens}

**Lens Used:** {lens name} - {why this lens was chosen}

## Tests
{Tests to write first — should fail now, pass after implementation}

## Implementation Steps
{Ordered steps, each making one or more of the above tests pass}

## Verification
{How to verify the implementation is correct}

Plan structure (multi-part — use for EACH part file):

# Implementation Plan: {Task Name} — PART {X} ONLY

> **PART {X} ONLY. Do not implement any other part. Other parts are separate tasks requiring explicit authorization.**

## Summary
{What THIS part covers. Explicitly note what is deferred: "Part B will cover X (separate task). Part C will cover Y (separate task)."}

## Proposed Architecture
{Mermaid diagram showing the proposed changes using the selected lens}

**Lens Used:** {lens name} - {why this lens was chosen}

## Tests
{Tests for THIS part only — should fail now, pass after THIS part's implementation}

## Implementation Steps
{Steps for THIS part only}

## Verification
{How to verify THIS part's implementation is correct}

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.