---
template: plan
version: 1.3
description: PDCA Plan phase document template with Context Anchor and Architecture considerations
variables:
  - feature: Feature name
  - date: Creation date (YYYY-MM-DD)
  - author: Author
  - project: Project name (from package.json or agents.md)
  - version: Project version (from package.json)
---

# {feature} Planning Document

> **Summary**: {One-line description}
>
> **Project**: {project}
> **Version**: {version}
> **Author**: {author}
> **Date**: {date}
> **Status**: Draft

---

## Executive Summary

| Perspective | Content |
|-------------|---------|
| **Problem** | {Core problem this feature solves} |
| **Solution** | {Selected solution approach} |
| **Function/UX Effect** | {Expected functional and UX impact} |
| **Core Value** | {Core value proposition} |

---

## Context Anchor

> Auto-generated from Executive Summary. Propagated to Design/Do documents for context continuity.

| Key | Value |
|-----|-------|
| **WHY** | {Core problem — extracted from Executive Summary Problem} |
| **WHO** | {Target users — extracted from Scope or Requirements} |
| **RISK** | {Top risk — extracted from Risks section} |
| **SUCCESS** | {Measurable criteria — extracted from Success Criteria} |
| **SCOPE** | {Phase breakdown — extracted from Scope section} |

---

## 1. Overview

### 1.1 Purpose

{The problem this feature solves or the goal it achieves}

### 1.2 Background

{Why this feature is needed, business context}

### 1.3 Related Documents

- Requirements: {link}
- References: {link}

---

## 2. Scope

### 2.1 In Scope

- [ ] {Included item 1}
- [ ] {Included item 2}
- [ ] {Included item 3}

### 2.2 Out of Scope

- {Excluded item 1}
- {Excluded item 2}

---

## 3. Requirements

### 3.1 Functional Requirements

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| FR-01 | {Requirement description} | High/Medium/Low | Pending |
| FR-02 | {Requirement description} | High/Medium/Low | Pending |

### 3.2 Non-Functional Requirements

| Category | Criteria | Measurement Method |
|----------|----------|-------------------|
| Performance | {e.g., Response time < 200ms} | {Tool/Method} |
| Security | {e.g., OWASP Top 10 compliance} | {Verification method} |
| Accessibility | {e.g., WCAG 2.1 AA} | {Verification method} |

---

## 4. Success Criteria

### 4.1 Definition of Done

- [ ] All functional requirements implemented
- [ ] Unit tests written and passing
- [ ] Code review completed
- [ ] Documentation completed

### 4.2 Quality Criteria

- [ ] Test coverage above 80%
- [ ] Zero lint errors
- [ ] Build succeeds

---

## 5. Risks and Mitigation

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| {Risk 1} | High/Medium/Low | High/Medium/Low | {Mitigation plan} |
| {Risk 2} | High/Medium/Low | High/Medium/Low | {Mitigation plan} |

---

## 6. Impact Analysis

> **Purpose**: List every existing consumer of the resources being changed.
> Changes can break existing functionality in unexpected ways.
> This section forces a full inventory of current usage before making changes.

### 6.1 Changed Resources

| Resource | Type | Change Description |
|----------|------|--------------------|
| {e.g., BilliContract model} | DB Model / API / Schema / Config | {What is being added, modified, or removed} |

### 6.2 Current Consumers

For each changed resource above, list **all** existing code paths that use it:

| Resource | Operation | Code Path | Impact |
|----------|-----------|-----------|--------|
| {resource} | CREATE | {e.g., user-app/contract/new → createBilliContract} | {None / Needs verification / Breaking} |
| {resource} | READ | {e.g., admin/queries/contract.ts → GET_CONTRACT_DETAIL} | {None / Needs verification / Breaking} |
| {resource} | UPDATE | {e.g., admin/hooks/use-contracts.ts → useUpdateContract} | {None / Needs verification / Breaking} |
| {resource} | DELETE | {e.g., admin/queries/contract.ts → DELETE_CONTRACT} | {None / Needs verification / Breaking} |

### 6.3 Verification

- [ ] All consumers listed above verified to work with the proposed changes
- [ ] No auth/permission changes break existing operations
- [ ] No field additions/removals break existing queries or mutations

---

## 7. Architecture Considerations

### 7.1 Project Level Selection

| Level | Characteristics | Recommended For | Selected |
|-------|-----------------|-----------------|:--------:|
| **Starter** | Simple structure (`components/`, `lib/`, `types/`) | Static sites, portfolios, landing pages | ☐ |
| **Dynamic** | Feature-based modules, BaaS integration (bkend.ai) | Web apps with backend, SaaS MVPs, fullstack apps | ☐ |
| **Enterprise** | Strict layer separation, DI, microservices | High-traffic systems, complex architectures | ☐ |

### 7.2 Key Architectural Decisions

| Decision | Options | Selected | Rationale |
|----------|---------|----------|-----------|
| Framework | Next.js / React / Vue | {selected} | {reason} |
| State Management | Context / Zustand / Redux / Jotai | {selected} | {reason} |
| API Client | fetch / axios / react-query | {selected} | {reason} |
| Form Handling | react-hook-form / formik / native | {selected} | {reason} |
| Styling | Tailwind / CSS Modules / styled-components | {selected} | {reason} |
| Testing | Jest / Vitest / Playwright | {selected} | {reason} |
| Backend | BaaS (bkend.ai) / Custom Server / Serverless | {selected} | Dynamic -> bkend.ai recommended |

### 7.3 Clean Architecture Approach

```
Selected Level: {Starter/Dynamic/Enterprise}

Folder Structure Preview:
┌─────────────────────────────────────────────────────┐
│ Starter:                                            │
│   src/components/, src/lib/, src/types/             │
├─────────────────────────────────────────────────────┤
│ Dynamic:                                            │
│   src/components/, src/features/, src/services/,    │
│   src/types/, src/lib/bkend.ts, .mcp.json           │
├─────────────────────────────────────────────────────┤
│ Enterprise:                                         │
│   src/presentation/, src/application/,              │
│   src/domain/, src/infrastructure/                  │
└─────────────────────────────────────────────────────┘
```

---

## 8. Convention Prerequisites

### 8.1 Existing Project Conventions

Check which conventions already exist in the project:

- [ ] `agents.md` has coding conventions section
- [ ] `docs/01-plan/conventions.md` exists (Phase 2 output)
- [ ] `CONVENTIONS.md` exists at project root
- [ ] ESLint configuration (`.eslintrc.*`)
- [ ] Prettier configuration (`.prettierrc`)
- [ ] TypeScript configuration (`tsconfig.json`)

### 8.2 Conventions to Define/Verify

| Category | Current State | To Define | Priority |
|----------|---------------|-----------|:--------:|
| **Naming** | {exists/missing} | {specific rules} | High |
| **Folder structure** | {exists/missing} | {structure rules} | High |
| **Import order** | {exists/missing} | {import rules} | Medium |
| **Environment variables** | {exists/missing} | {env var list} | Medium |
| **Error handling** | {exists/missing} | {error patterns} | Medium |

### 8.3 Environment Variables Needed

| Variable | Purpose | Scope | To Be Created |
|----------|---------|-------|:-------------:|
| `NEXT_PUBLIC_API_URL` | API endpoint | Client | ☐ |
| `DATABASE_URL` | DB connection | Server | ☐ |
| `AUTH_SECRET` | Auth secret key | Server | ☐ |
| {variable} | {purpose} | {scope} | ☐ |

### 8.4 Pipeline Integration

If using 9-phase Development Pipeline, check the following:

| Phase | Status | Document Location | Command |
|-------|:------:|-------------------|---------|
| Phase 1 (Schema) | ☐ | `docs/01-plan/schema.md` | `/pipeline-next` |
| Phase 2 (Convention) | ☐ | `docs/01-plan/conventions.md` | `/pipeline-next` |

**Pipeline Templates Available:**
- `templates/pipeline/phase-1-schema.template.md`
- `templates/pipeline/phase-2-convention.template.md`

**Quick Start:**
```bash
# Check pipeline status
/pipeline-status

# Start pipeline from Phase 1
/pipeline-start

# Go to next phase
/pipeline-next
```

---

## 9. Next Steps

1. [ ] Write design document (`{feature}.design.md`)
2. [ ] Team review and approval
3. [ ] Start implementation

---

## Version History

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 0.1 | {date} | Initial draft | {author} |