Initial commit

2025-11-30 09:01:45 +08:00
commit befff05008
38 changed files with 9964 additions and 0 deletions
--- a/commands/think.md
+++ b/commands/think.md
@@ -0,0 +1,663 @@
+---
+description: >
+  Create a comprehensive Statement of Work (SOW) for feature development or problem solving.
+  Use when planning complex tasks, defining acceptance criteria, or structuring implementation approaches.
+  Ideal for tasks requiring detailed analysis, risk assessment, and structured planning documentation.
+  構造化された計画文書（SOW）を生成。複雑なタスクの計画、受け入れ基準の定義、実装アプローチの構造化が必要な場合に使用。
+allowed-tools: Bash(git log:*), Bash(git diff:*), Bash(git branch:*), Read, Write, Glob, Grep, LS, Task
+model: inherit
+argument-hint: "[feature or problem description]"
+---
+
+# /think - Simple SOW Generator
+
+## Purpose
+
+Create a comprehensive Statement of Work (SOW) as a static planning document for feature development or problem solving.
+
+**Simplified**: Focus on planning and documentation without complex automation.
+
+**Output Verifiability**: All analyses, assumptions, and solutions marked with ✓/→/? to distinguish facts from inferences per AI Operation Principle #4.
+
+## Context Engineering Integration
+
+**IMPORTANT**: Before starting analysis, check for existing research context.
+
+### Automatic Context Discovery
+
+```bash
+# Search for latest research context files
+!`find .claude/workspace/research ~/.claude/workspace/research -name "*-context.md" 2>/dev/null | sort -r | head -1`
+```
+
+### Context Loading Strategy
+
+1. **Check for recent research**: Look for context files in the last 24 hours
+2. **Prioritize project-local**: `.claude/workspace/research/` over global `~/.claude/workspace/research/`
+3. **Extract key information**: Purpose, Prerequisites, Available Data, Constraints
+4. **Integrate into planning**: Use research findings to inform SOW creation
+
+### Context-Informed Planning
+
+If research context is found:
+
+- **🎯 Purpose**: Align SOW goals with research objectives
+- **📋 Prerequisites**: Build on verified facts, validate assumptions
+- **📊 Available Data**: Reference discovered files and stack
+- **🔒 Constraints**: Respect identified limitations
+
+**Benefits**:
+
+- **Higher confidence**: Planning based on actual codebase knowledge
+- **Fewer assumptions**: Replace unknowns with verified facts
+- **Better estimates**: Realistic based on discovered complexity
+- **Aligned goals**: Purpose-driven from research to implementation
+
+## Codebase Analysis Phase
+
+### Purpose
+
+Before creating SOW, analyze the existing codebase to understand:
+
+- Similar existing implementations
+- Current architecture patterns
+- Impact scope and affected modules
+- Dependencies and integration points
+
+### When to Invoke Plan Agent
+
+**Default behavior** - Plan agent is invoked by default unless explicitly greenfield:
+
+```typescript
+// Decision logic
+const needsCodebaseAnalysis =
+  // Default: invoke Plan agent unless explicitly greenfield
+  !/new project|from scratch|prototype|poc/i.test(featureDescription);
+```
+
+**Skip conditions** - Plan agent is NOT invoked only for:
+
+- Greenfield projects ("new project", "from scratch")
+- Prototypes and POCs
+- Standalone utilities
+- Documentation-only changes
+
+### Plan Agent Invocation
+
+When conditions are met, invoke Plan agent with medium thoroughness:
+
+```typescript
+Task({
+  subagent_type: "Plan",
+  model: "haiku",
+  thoroughness: "medium",
+  description: "Analyze codebase for feature context",
+  prompt: `
+Feature: "${featureDescription}"
+
+Investigate:
+1. Existing patterns: similar implementations (file:line), architecture [✓]
+2. Related modules: affected files, dependencies, integration points [✓]
+3. Tech stack: libraries, conventions, testing [✓]
+4. Recommendations: approach, reusable modules, challenges [→]
+5. Impact: scope estimate, breaking changes, risks [→]
+
+Return findings with markers: [✓] verified, [→] inferred, [?] unknown.
+  `
+})
+```
+
+### Integration with SOW Generation
+
+Plan agent findings are incorporated into SOW sections:
+
+**Problem Analysis**:
+
+```markdown
+### Current State [✓]
+${planFindings.existingPatterns}
+- Located at: ${planFindings.fileReferences}
+- Currently using: ${planFindings.techStack}
+```
+
+**Solution Design**:
+
+```markdown
+### Recommended Approach [→]
+Based on codebase analysis:
+- Follow pattern from: ${planFindings.similarImplementation}
+- Integrate with: ${planFindings.integrationPoints}
+- Reuse: ${planFindings.reusableModules}
+```
+
+**Dependencies**:
+
+```markdown
+### Existing [✓]
+${planFindings.currentDependencies}
+
+### New [→]
+${inferredNewDependencies}
+```
+
+**Risks & Mitigations**:
+
+```markdown
+### High Confidence Risks [✓]
+${planFindings.identifiedRisks}
+
+### Potential Risks [→]
+${planFindings.impactAssessment}
+```
+
+### Benefits
+
+- **Higher confidence**: Planning based on actual codebase knowledge
+- **Fewer assumptions**: Replace [?] unknowns with [✓] verified facts
+- **Better alignment**: Solutions consistent with existing patterns
+- **Realistic estimates**: Based on discovered complexity
+- **Reduced surprises**: Identify integration challenges upfront
+
+### Cost-Benefit Analysis
+
+| Metric | Without Plan | With Plan |
+|--------|-------------|-----------|
+| **SOW Accuracy** | [→] 65-75% | [✓] 85-95% |
+| **Assumptions** | Many [?] items | Mostly [✓] items |
+| **Implementation surprises** | High | Low |
+| **Additional cost** | $0 | +$0.05-0.15 |
+| **Additional time** | 0s | +5-15s |
+
+[→] Haiku-powered for minimal cost impact
+
+## Dynamic Project Context
+
+### Current State Analysis
+
+```bash
+!`git branch --show-current`
+!`git log --oneline -5`
+```
+
+## SOW Structure
+
+### Required Sections
+
+**IMPORTANT**: Use ✓/→/? markers throughout to distinguish facts, inferences, and assumptions.
+
+```markdown
+# SOW: [Feature Name]
+Version: 1.0.0
+Status: Draft
+Created: [Date]
+
+## Executive Summary
+[High-level overview with confidence markers]
+
+## Problem Analysis
+Use markers to indicate confidence:
+- [✓] Verified issues (confirmed by logs, user reports, code review)
+- [→] Inferred problems (reasonable deduction from symptoms)
+- [?] Suspected issues (requires investigation)
+
+## Assumptions & Prerequisites
+**NEW SECTION**: Explicitly state what we're assuming to be true.
+
+### Verified Facts (✓)
+- [✓] Fact 1 - Evidence: [source]
+- [✓] Fact 2 - Evidence: [file:line]
+
+### Working Assumptions (→)
+- [→] Assumption 1 - Based on: [reasoning]
+- [→] Assumption 2 - Inferred from: [evidence]
+
+### Unknown/Needs Verification (?)
+- [?] Unknown 1 - Need to check: [what/where]
+- [?] Unknown 2 - Requires: [action needed]
+
+## Solution Design
+### Proposed Approach
+[Main solution with confidence level]
+
+### Alternatives Considered
+1. [✓/→/?] Option A - [Pro/cons with evidence]
+2. [✓/→/?] Option B - [Pro/cons with reasoning]
+
+### Recommendation
+[Chosen solution] - Confidence: [✓/→/?]
+Rationale: [Evidence-based reasoning]
+
+## Test Plan
+
+### Unit Tests (Priority: High)
+- [ ] Function: `calculateDiscount(count)` - Returns 20% for 15+ purchases
+- [ ] Function: `calculateDiscount(count)` - Returns 10% for <15 purchases
+- [ ] Function: `calculateDiscount(count)` - Handles zero/negative input
+
+### Integration Tests (Priority: Medium)
+- [ ] API: POST /users - Creates user with valid data
+- [ ] API: POST /users - Rejects duplicate email with 409
+
+### E2E Tests (Priority: Low)
+- [ ] User registration flow - Complete signup process
+
+## Acceptance Criteria
+Mark each with confidence:
+- [ ] [✓] Criterion 1 - Directly from requirements
+- [ ] [→] Criterion 2 - Inferred from user needs
+- [ ] [?] Criterion 3 - Assumed, needs confirmation
+
+## Implementation Plan
+[Phases and steps with dependencies noted]
+
+## Success Metrics
+- [✓] Metric 1 - Measurable: [how]
+- [→] Metric 2 - Estimated: [basis]
+
+## Risks & Mitigations
+### High Confidence Risks (✓)
+- Risk 1 - Evidence: [past experience, data]
+- Mitigation: [specific action]
+
+### Potential Risks (→)
+- Risk 2 - Inferred from: [analysis]
+- Mitigation: [contingency plan]
+
+### Unknown Risks (?)
+- Risk 3 - Monitor: [what to watch]
+- Mitigation: [preparedness]
+
+## Verification Checklist
+Before starting implementation, verify:
+- [ ] All [?] items have been investigated
+- [ ] Assumptions [→] have been validated
+- [ ] Facts [✓] have current evidence
+```
+
+## Key Features
+
+### 1. Problem Definition
+
+- Clear articulation of the issue
+- Impact assessment
+- Stakeholder identification
+- **Confidence markers**: ✓ verified / → inferred / ? suspected
+
+### 2. Assumptions & Prerequisites
+
+- Explicit statement of what's assumed
+- Distinction between facts and inferences
+- Clear identification of unknowns
+- **Prevents**: Building on false assumptions
+
+### 3. Solution Exploration
+
+- Multiple approaches considered
+- Trade-off analysis with evidence
+- Recommendation with rationale
+- **Each option marked**: ✓/→/? for confidence level
+
+### 4. Acceptance Criteria
+
+- Clear, testable criteria
+- User-facing outcomes
+- Technical requirements
+- **Confidence per criterion**: Know which need verification
+
+### 5. Risk Assessment
+
+- Technical risks with evidence
+- Timeline risks with reasoning
+- Mitigation strategies
+- **Categorized by confidence**: ✓ confirmed / → potential / ? unknown
+
+## Output
+
+### Dual-Document Generation
+
+The `/think` command generates **two complementary documents**:
+
+1. **SOW (Statement of Work)** - High-level planning
+2. **Spec (Specification)** - Implementation-ready details
+
+### Generation Process
+
+**IMPORTANT**: Both documents MUST be generated using the Write tool:
+
+1. **Create output directory**: `.claude/workspace/sow/[timestamp]-[feature-name]/`
+2. **Generate sow.md**: Use SOW template structure (sections 1-8)
+3. **Generate spec.md**: Use Spec template structure (sections 1-10)
+4. **Confirm creation**: Display save locations with ✅ indicators
+
+**Example**:
+
+```bash
+# After generating both documents
+✅ SOW saved to: .claude/workspace/sow/2025-01-18-auth-feature/sow.md
+✅ Spec saved to: .claude/workspace/sow/2025-01-18-auth-feature/spec.md
+```
+
+### Output Location (Auto-Detection)
+
+Both files are saved using git-style directory search:
+
+1. **Search upward** from current directory for `.claude/` directory
+2. **If found**: Save to `.claude/workspace/sow/[timestamp]-[feature]/` (project-local)
+3. **If not found**: Save to `~/.claude/workspace/sow/[timestamp]-[feature]/` (global)
+
+**Output Structure**:
+
+```text
+.claude/workspace/sow/[timestamp]-[feature]/
+├── sow.md       # Statement of Work (planning)
+└── spec.md      # Specification (implementation details)
+```
+
+**Feedback**: The save location is displayed with context indicator:
+
+- `✅ SOW saved to: .claude/workspace/sow/... (Project-local: .claude/ detected)`
+- `✅ Spec saved to: .claude/workspace/sow/... (Project-local: .claude/ detected)`
+
+**Benefits**:
+
+- **Zero-config**: Automatically adapts to project structure
+- **Team sharing**: Project-local enables git-based sharing
+- **Personal notes**: Global storage for exploratory work
+- **Flexible**: Create `.claude/` to switch to project-local mode
+- **Integrated workflow**: spec.md automatically used by `/review` and `/code`
+
+Features:
+
+- **SOW**: Planning document with acceptance criteria
+- **Spec**: Implementation-ready specifications
+- Clear acceptance criteria with confidence markers
+- Explicit assumptions and prerequisites section
+- Risk assessment by confidence level
+- Implementation roadmap
+- **Output Verifiability**: All claims marked ✓/→/? with evidence
+
+## Integration
+
+```bash
+/think "feature"    # Create planning SOW
+/todos              # Track implementation separately
+```
+
+## Example Usage
+
+```bash
+/think "Add user authentication with OAuth"
+```
+
+Generates:
+
+- Comprehensive planning document
+- 8-12 Acceptance Criteria
+- Risk assessment
+- Implementation phases
+
+## Simplified Workflow
+
+1. **Planning Phase**
+   - Use `/think` to create SOW
+   - **Automatic codebase analysis** (Plan agent invoked if applicable)
+   - Review and refine plan with verified context
+
+2. **Execution Phase**
+   - Use TodoWrite for task tracking
+   - Reference SOW for requirements
+
+3. **Review Phase**
+   - Check against acceptance criteria
+   - Update documentation as needed
+
+## Related Commands
+
+- `/code` - Implementation with TDD
+- `/test` - Testing and verification
+- `/review` - Code review
+
+## Specification Document (spec.md) Structure
+
+The spec.md provides implementation-ready details that complement the high-level SOW.
+
+### Spec Template
+
+```markdown
+# Specification: [Feature Name]
+
+Version: 1.0.0
+Based on: SOW v1.0.0
+Last Updated: [Date]
+
+---
+
+## 1. Functional Requirements
+
+### 1.1 Core Functionality
+[✓] FR-001: [Clear, testable requirement]
+- Input: [Expected inputs with types]
+- Output: [Expected outputs]
+- Validation: [Validation rules]
+
+[→] FR-002: [Inferred requirement]
+- [Details with confidence marker]
+
+### 1.2 Edge Cases
+[→] EC-001: [Edge case description]
+- Action: [How to handle]
+- [?] To confirm: [Unclear aspects]
+
+---
+
+## 2. API Specification (Backend features)
+
+### 2.1 [HTTP METHOD] /path/to/endpoint
+
+**Request**:
+```json
+{
+  "field": "type and example"
+}
+```
+
+**Response (Success - 200)**:
+
+```json
+{
+  "result": "expected structure"
+}
+```
+
+**Response (Error - 4xx/5xx)**:
+
+```json
+{
+  "error": "ERROR_CODE",
+  "message": "Human-readable message"
+}
+```
+
+---
+
+## 3. Data Model
+
+### 3.1 [Entity Name]
+
+```typescript
+interface EntityName {
+  id: string;              // Description, constraints
+  field: type;             // Purpose, validation rules
+  created_at: Date;
+  updated_at: Date;
+}
+```
+
+### 3.2 Relationships
+
+- Entity A → Entity B: [Relationship type and constraints]
+
+---
+
+## 4. UI Specification (Frontend features)
+
+### 4.1 [Screen/Component Name]
+
+**Layout**:
+
+- Element 1: position, sizing, placeholder text
+- Element 2: styling details
+
+**Validation**:
+
+- Real-time: [When to validate]
+- Submit: [Final validation rules]
+- Error display: [How to show errors]
+
+**Responsive**:
+
+- Mobile (< 768px): [Layout adjustments]
+- Desktop: [Default layout]
+
+### 4.2 User Interactions
+
+- Action: [User action] → Result: [System response]
+
+---
+
+## 5. Non-Functional Requirements
+
+### 5.1 Performance
+
+[✓] NFR-001: [Measurable performance requirement]
+[→] NFR-002: [Inferred performance target]
+
+### 5.2 Security
+
+[✓] NFR-003: [Security requirement with evidence]
+[→] NFR-004: [Security consideration]
+
+### 5.3 Accessibility
+
+[→] NFR-005: [Accessibility standard]
+[?] NFR-006: [Needs confirmation]
+
+---
+
+## 6. Dependencies
+
+### 6.1 External Libraries
+
+[✓] library-name: ^version (purpose)
+[→] optional-library: ^version (if needed, basis)
+
+### 6.2 Internal Services
+
+[✓] ServiceName: [Purpose and interface]
+[?] UnclearService: [Needs investigation]
+
+---
+
+## 7. Test Scenarios
+
+### 7.1 Unit Tests
+
+```typescript
+describe('FeatureName', () => {
+  it('[✓] handles typical case', () => {
+    // Given: setup
+    // When: action
+    // Then: expected result
+  });
+
+  it('[→] handles edge case', () => {
+    // Inferred behavior
+  });
+});
+```
+
+### 7.2 Integration Tests
+
+[Key integration scenarios]
+
+### 7.3 E2E Tests (if UI)
+
+[Critical user flows]
+
+---
+
+## 8. Known Issues & Assumptions
+
+### Assumptions (→)
+
+1. [Assumption 1 - basis for assumption]
+2. [Assumption 2 - needs confirmation]
+
+### Unknown / Need Verification (?)
+
+1. [Unknown 1 - what needs checking]
+2. [Unknown 2 - where to verify]
+
+---
+
+## 9. Implementation Checklist
+
+- [ ] [Specific implementation step 1]
+- [ ] [Specific implementation step 2]
+- [ ] Unit tests (coverage >80%)
+- [ ] Integration tests
+- [ ] Documentation update
+
+---
+
+## 10. References
+
+- SOW: `sow.md`
+- Related specs: [Links to related specifications]
+- API docs: [Links to API documentation]
+
+```markdown
+
+### Spec Generation Guidelines
+
+1. **Use ✓/→/? markers consistently** - Align with SOW's Output Verifiability
+2. **Be implementation-ready** - Developers should be able to code directly from spec
+3. **Include concrete examples** - API requests/responses, data structures, UI layouts
+4. **Define test scenarios** - Clear Given-When-Then format
+5. **Document unknowns explicitly** - [?] markers for items requiring clarification
+
+### When to Generate Spec
+
+- **Always with SOW**: Spec is generated alongside SOW by default
+- **Update together**: When SOW changes, update spec accordingly
+- **Reference in reviews**: `/review` will automatically reference spec.md
+
+## Applied Principles
+
+### Output Verifiability (AI Operation Principle #4)
+
+- **Distinguish facts from inferences**: ✓/→/? markers
+- **Provide evidence**: File paths, line numbers, sources
+- **State confidence levels**: Explicit about certainty
+- **Admit unknowns**: [?] for items needing investigation
+- **Prevents**: Building plans on false assumptions
+
+### Occam's Razor
+
+- Simple, static documents
+- No complex automation
+- Clear separation of concerns
+
+### Progressive Enhancement
+
+- Start with basic SOW
+- Add detail as needed
+- No premature optimization
+- **Assumptions section**: Identify what to verify first
+
+### Readable Documentation
+
+- Clear structure
+- Plain language
+- Actionable criteria
+- **Confidence markers**: Visual clarity for trust level