piv-plan-implementation

name	piv-plan-implementation
description	Creates a comprehensive, context-rich implementation plan through deep codebase analysis, a short clarifying interview, and external research. Accepts a tracker ticket (a Jira/Linear/GitHub key or URL, fetched from the tracker) or a free-form feature request. Use when you have a ticket or feature and need a one-pass-ready plan before writing any code.
argument-hint	[ticket key/URL (fetched from your tracker), or a free-form feature description]

Plan a new task

Feature: $ARGUMENTS

Resolve the input first

$ARGUMENTS is either a tracker ticket (a key like ACC-30, or a Jira / Linear / GitHub issue URL) or a free-form feature description. Tell them apart and handle each:

• A ticket (a key such as ABC-123, or an issue URL): fetch it from the tracker before you plan (Jira via the Atlassian MCP, GitHub via gh issue view, etc.). Read its summary, acceptance criteria, and per-ticket context. Then follow its links up to the epic and the epic's linked architecture page (Confluence via the Atlassian MCP) and inherit those decisions (see "Inherit, don't re-decide" below). Never plan from the bare key; the ticket body plus its epic and architecture are the real input.
• A free-form description: plan directly from it (greenfield or ad-hoc), asking clarifying questions as needed.

Mission

Transform a feature request into a comprehensive implementation plan through systematic codebase analysis, external research, and strategic planning.

Core Principle: We do NOT write code in this phase. Our goal is to create a context-rich implementation plan that enables one-pass implementation success for ai agents.

Key Philosophy: Context is King. The plan must contain ALL information needed for implementation - patterns, mandatory reading, documentation, validation commands - so the execution agent succeeds on the first attempt.

Inherit, don't re-decide: This is a per-ticket plan. If the ticket belongs to an epic that already has architecture decisions — a linked architecture page (e.g. a Confluence page from the plan-architecture skill, reached from the ticket's epic), an ## Architecture / ## Engineering section on the epic, or a local architecture.md / engineering-plan.md — read it first and treat its cross-cutting calls (stack & versions, data model, security boundaries, the seams new code plugs into) as already decided. Inherit them; don't reopen them. Plan only what's left at the ticket level: the specific files, the local patterns to mirror, the tests. If a ticket genuinely needs to break an epic-level decision, flag it in Open Questions rather than silently diverging.

Planning Process

Phase 1: Feature Understanding

Deep Feature Analysis:

• Extract the core problem being solved
• Identify user value and business impact
• Determine feature type: New Capability/Enhancement/Refactor/Bug Fix
• Assess complexity: Low/Medium/High
• Map affected systems and components

Create User Story Format Or Refine If Story Was Provided By The User:

As a <type of user>
I want to <action/goal>
So that <benefit/value>

Phase 2: Codebase Intelligence Gathering

Use specialized agents and parallel analysis:

1. Project Structure Analysis

• Detect primary language(s), frameworks, and runtime versions
• Map directory structure and architectural patterns
• Identify service/component boundaries and integration points
• Locate configuration files (pyproject.toml, package.json, etc.)
• Find environment setup and build processes

2. Pattern Recognition (Use specialized subagents when beneficial)

• Search for similar implementations in codebase
• Identify coding conventions:
  • Naming patterns (CamelCase, snake_case, kebab-case)
  • File organization and module structure
  • Error handling approaches
  • Logging patterns and standards
• Extract common patterns for the feature's domain
• Document anti-patterns to avoid
• Check CLAUDE.md for project-specific rules and conventions

3. Dependency Analysis

• Catalog external libraries relevant to feature
• Understand how libraries are integrated (check imports, configs)
• Find relevant documentation in docs/, ai_docs/, .claude/references or ai-wiki if available
• Note library versions and compatibility requirements

4. Testing Patterns

• Identify test framework and structure (pytest, jest, etc.)
• Find similar test examples for reference
• Understand test organization (unit vs integration)
• Note coverage requirements and testing standards

5. Integration Points

• Identify existing files that need updates
• Determine new files that need creation and their locations
• Map router/API registration patterns
• Understand database/model patterns if applicable
• Identify authentication/authorization patterns if relevant

Clarify Ambiguities — GATE:

Codebase analysis is done, so the open questions are now specific. This is the one moment where you know enough to ask well and have not yet written anything. GATE means: post the questions, then stop. End the turn and wait for the answers. Do not ask and answer in the same breath, and do not roll into Phase 3.

Ask in one cluster, numbered, 3-6 questions max, each carrying a recommended default so answering is cheap ("I'll mirror the first unless you say otherwise"). Draw them only from what the analysis actually left open:

1. Scope boundary — the adjacent thing a reasonable reader would assume is in scope. Confirm it is out.
2. Pattern fork — two existing patterns both fit. Name both with file:line and ask which to mirror.
3. Contract shape — the API surface, payload, or data-model change the ticket implies but never states.
4. Failure behavior — what happens on the error path the ticket is silent about.
5. Preference — a library or trade-off with no precedent in this codebase to inherit.
6. Done — an acceptance criterion that is missing, or written so that it cannot be checked.

Skip any category with nothing genuinely open; never manufacture questions to fill the list. If the ticket, its epic and the architecture doc genuinely settle everything, say so in one line and proceed. Silence is not the same as clearance.

Thin answers: reflect a vague answer back as the concrete choice it leaves open ("'handle errors gracefully' — a 4xx with a message, or retry then 503?") and ask once more. Never upgrade a vague answer into a confident plan.

If they decline ("just write it"): honour it, but name what you are guessing. Every unanswered item becomes an Assumed — <the assumption>, confirm before execution line in OPEN QUESTIONS / ASSUMPTIONS, and the task it affects carries a **GOTCHA** naming it. Never guess silently.

Already settled upstream: anything the ticket, its epic, or the linked architecture page already answers is not open. Inherit it and skip (see "Inherit, don't re-decide").

Phase 3: External Research & Documentation

Use specialized subagents when beneficial for external research:

Documentation Gathering:

• Research latest library versions and best practices
• Find official documentation with specific section anchors
• Locate implementation examples and tutorials
• Identify common gotchas and known issues
• Check for breaking changes and migration guides

Technology Trends:

• Research current best practices for the technology stack
• Find relevant blog posts, guides, or case studies
• Identify performance optimization patterns
• Document security considerations

Compile Research References:

## Relevant Documentation

- [Library Official Docs](https://example.com/docs#section)
  - Specific feature implementation guide
  - Why: Needed for X functionality
- [Framework Guide](https://example.com/guide#integration)
  - Integration patterns section
  - Why: Shows how to connect components

Phase 4: Deep Strategic Thinking

Think Harder About:

• How does this feature fit into the existing architecture?
• What are the critical dependencies and order of operations?
• What could go wrong? (Edge cases, race conditions, errors)
• How will this be tested comprehensively?
• What performance implications exist?
• Are there security considerations?
• How maintainable is this approach?

Design Decisions:

• Choose between alternative approaches with clear rationale
• Design for extensibility and future modifications
• Plan for backward compatibility if needed
• Consider scalability implications

Phase 5: Plan Structure Generation

Create comprehensive plan with the following structure:

Whats below here is a template for you to fill for the implementation agent:

# Feature: <feature-name>

The following plan should be complete, but its important that you validate documentation and codebase patterns and task sanity before you start implementing.

Pay special attention to naming of existing utils types and models. Import from the right files etc.

## Feature Description

<Detailed description of the feature, its purpose, and value to users>

## User Story

As a <type of user>
I want to <action/goal>
So that <benefit/value>

## Problem Statement

<Clearly define the specific problem or opportunity this feature addresses>

## Solution Statement

<Describe the proposed solution approach and how it solves the problem>

## Out of Scope / Non-Goals

<Explicitly bound                     ' —             >

 Not included:  (defer to )
 Not changing: 



: [New Capability/Enhancement/Refactor/Bug Fix]
: [Low/Medium/High]
: [List of main components/services]
: [External libraries or services required]





:    ·   : 

 (plans this builds on or inherits decisions from):

  - Why: shares the auth seam / reuses the X service

 (plans that extend or supersede this — append as follow-ups get created):

 (none yet)

---







  (lines 15-45) - Why: Contains pattern for X that we'll mirror
  (lines 100-120) - Why: Database model structure to follow
  - Why: Test pattern example



  - Service implementation for X functionality
  - Data model for Y resource
  - Unit tests for new service



 []()
 Specific section: Authentication setup
 Why: Required for implementing secure endpoints
 []()
 Specific section: Database integration
 Why: Shows proper async database patterns





 (for example)

 (for example)

 (for example)

 (for example)

---



Phases run  — each assumes the phase above it is done. Where that is NOT the true dependency, make it explicit with a  line under the phase header, and a  line where two phases don't block each other. Independent phases are candidates to run in  (e.g. separate worktrees / parallel loops). Only annotate where it changes execution order or unlocks parallelism — skip the obvious sequential case.







 Set up base structures (schemas, types, interfaces)
 Configure necessary dependencies
 Create foundational utilities or helpers



 Phase 1 (needs the base schemas/types)





 Implement core business logic
 Create service layer components
 Add API endpoints or interfaces
 Implement data models







 Connect to existing routers/handlers
 Register new components
 Update configuration files
 Add middleware or interceptors if needed







 Implement unit tests for each component
 Create integration tests for feature workflow
 Add edge case tests
 Validate against acceptance criteria

---



IMPORTANT: Execute every task in order, top to bottom. Each task is atomic and independently testable.



Use information-dense keywords for clarity:

 : New files or components
 : Modify existing files
 : Insert new functionality into existing code
 : Delete deprecated code
 : Restructure without changing behavior
 : Copy pattern from elsewhere in codebase

Output Format

Filename: .claude/plans/{kebab-case-descriptive-name}.md

• Replace {kebab-case-descriptive-name} with short, descriptive feature name
• Examples: add-user-authentication.md, implement-search-api.md, refactor-database-layer.md

Directory: Create .claude/plans/ if it doesn't exist

Quality Criteria

Context Completeness ✓

• All necessary patterns identified and documented
• External library usage documented with links
• Integration points clearly mapped
• Gotchas and anti-patterns captured
• Every task has executable validation command
• Phase 2's clarifying cluster was asked and answered, or explicitly recorded as nothing open

Implementation Ready ✓

• Another developer could execute without additional context
• Tasks ordered by dependency (can execute top-to-bottom)
• Each task is atomic and independently testable
• Pattern references include specific file:line numbers

Pattern Consistency ✓

• Tasks follow existing codebase conventions
• New patterns justified with clear rationale
• No reinvention of existing patterns or utils
• Testing approach matches project standards

Information Density ✓

• No generic references (all specific and actionable)
• URLs include section anchors when applicable
• Task descriptions use codebase keywords
• Validation commands are non interactive executable

Success Metrics

One-Pass Implementation: Execution agent can complete feature without additional research or clarification — clarification the user owes the plan belongs in Phase 2's gate, not deferred to the execution agent

Validation Complete: Every task has at least one working validation command

Context Rich: The Plan passes "No Prior Knowledge Test" - someone unfamiliar with codebase can implement using only Plan content

Confidence Score: #/10 that execution will succeed on first attempt

Report

After creating the Plan, provide:

• Summary of feature and approach
• Full path to created Plan file
• Complexity assessment
• Key implementation risks or considerations
• Estimated confidence score for one-pass success