pmp-gywd 3.3.0

package/commands/gywd/history.md

@@ -0,0 +1,278 @@
+---
+name: GYWD:history
+description: Query codebase temporal history - understand evolution, not just state
+argument-hint: "<query> [--file <path>] [--since <date>] [--author <name>]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<objective>
+Enable natural language queries against codebase history.
+
+Current tools show you snapshots. This shows you the **timeline**.
+
+Every version of your code exists simultaneously in understanding. Query the evolution, not just the current state.
+</objective>
+
+<philosophy>
+Understanding code requires understanding its history:
+
+- Why did this change from X to Y?
+- What problems did the old approach have?
+- What patterns have emerged over time?
+- What refactorings have been attempted and reverted?
+- What areas are volatile vs stable?
+
+The temporal dimension is where decisions become visible.
+</philosophy>
+
+<query_types>
+## Supported Query Patterns
+
+### Evolution Queries
+- "When did we start using this pattern?"
+- "What did authentication look like before the rewrite?"
+- "How has this file evolved over time?"
+- "What was removed in the last major refactor?"
+
+### Causation Queries
+- "Why did we change the error handling?"
+- "What bug led to this fix?"
+- "What drove the migration from X to Y?"
+
+### Pattern Queries
+- "What files always change together?"
+- "Who usually works on this area?"
+- "What's the typical commit pattern here?"
+
+### Stability Queries
+- "What areas have been most volatile?"
+- "What hasn't changed in 6 months?"
+- "What gets reverted most often?"
+
+### Prediction Queries
+- "Based on evolution, what will need work soon?"
+- "What patterns suggest technical debt?"
+- "What areas are due for refactoring?"
+</query_types>
+
+<process>
+## Query Processing
+
+1. **Parse query intent:**
+   ```
+   Query: "Why did we stop using Redux?"
+
+   Intent: causation
+   Subject: "Redux"
+   Timeframe: historical (removal)
+   Output: decision context
+   ```
+
+2. **Gather temporal data:**
+
+   ```bash
+   # Find when Redux was removed
+   git log -p --all -S "redux" -- "*.ts" "*.tsx"
+
+   # Find related commits
+   git log --grep="redux\|state management" --oneline
+
+   # Find PR/issue references
+   git log --format="%s %b" | grep -i "redux"
+   ```
+
+3. **Build timeline:**
+   ```
+   Timeline: Redux Usage
+   ├── 2023-01-15: Added Redux (commit abc)
+   │   └── "Initial state management setup"
+   ├── 2023-06-20: Redux Toolkit migration (commit def)
+   │   └── "Simplify Redux boilerplate"
+   ├── 2024-02-10: Zustand experiment (branch feature/zustand)
+   │   └── "Testing lighter alternative"
+   ├── 2024-03-01: Redux removed (commit ghi)
+   │   └── "Migrated to Zustand - 60% less code"
+   └── Current: Zustand in use
+   ```
+
+4. **Extract decision context:**
+   - Commit messages explaining why
+   - PR descriptions with rationale
+   - Issue references
+   - Code comments during transition
+
+5. **Generate response:**
+   ```markdown
+   ## Why We Stopped Using Redux
+
+   **Timeline:** Redux was used from Jan 2023 to Mar 2024 (14 months)
+
+   **The Decision:**
+   In March 2024, Redux was replaced with Zustand (commit ghi, PR #234).
+
+   **Why:**
+   - "60% less boilerplate code" (PR description)
+   - "Simpler mental model for new developers" (commit message)
+   - "No more action/reducer ceremony" (code comment)
+
+   **The Trigger:**
+   Issue #189: "State management complexity slowing onboarding"
+
+   **What Changed:**
+   - Removed: redux, react-redux, @reduxjs/toolkit
+   - Added: zustand
+   - Modified: 34 files
+   - Net: -2,400 lines
+
+   **Related Decisions:**
+   - DEC-023: "Prefer simplicity over enterprise patterns"
+   ```
+</process>
+
+<commands>
+## Subcommands
+
+### /gywd:history <query>
+Natural language query against history.
+
+```
+/gywd:history "When did we add TypeScript?"
+/gywd:history "What did the API layer look like before microservices?"
+/gywd:history "Why was the cache layer removed?"
+```
+
+### /gywd:history --file <path>
+Show evolution of specific file.
+
+```
+/gywd:history --file src/auth/login.ts
+
+Output:
+## Evolution: src/auth/login.ts
+
+Created: 2023-02-10 by @alice
+Total commits: 47
+Major rewrites: 2
+
+Timeline:
+├── v1 (Feb-Jun 2023): Basic username/password
+├── v2 (Jul 2023): Added OAuth providers
+├── v3 (Jan 2024): Complete rewrite for SSO
+└── Current: SSO with fallback to OAuth
+
+Stability: Medium (12 changes in last 6 months)
+Volatility trend: Decreasing ↓
+```
+
+### /gywd:history --author <name>
+Show developer's contribution patterns.
+
+```
+/gywd:history --author alice
+
+Output:
+## Contribution Pattern: @alice
+
+Active: 2023-01 to present
+Total commits: 234
+Primary areas: auth/, api/, tests/
+
+Expertise signals:
+- 80% of auth/ commits
+- Original author of OAuth integration
+- Primary reviewer for security PRs
+
+Typical patterns:
+- Commits in morning (9-11am)
+- Large refactors on Fridays
+- Always includes tests
+```
+
+### /gywd:history --hotspots
+Show volatile areas that may need attention.
+
+```
+/gywd:history --hotspots
+
+Output:
+## Code Hotspots (Last 90 Days)
+
+| File | Changes | Authors | Churn | Risk |
+|------|---------|---------|-------|------|
+| src/api/orders.ts | 23 | 5 | High | 🔴 |
+| src/utils/date.ts | 18 | 3 | High | 🟠 |
+| src/auth/session.ts | 15 | 2 | Med | 🟡 |
+
+Patterns detected:
+- orders.ts: Possible design instability
+- date.ts: Edge case fixes (consider library)
+- session.ts: Feature additions (healthy)
+```
+
+### /gywd:history --predict
+Predict future changes based on patterns.
+
+```
+/gywd:history --predict
+
+Output:
+## Predicted Changes (Next 30 Days)
+
+Based on evolution patterns:
+
+1. **src/api/payments.ts** (78% confidence)
+   - Pattern: Similar evolution to orders.ts
+   - Trigger: Usually follows order system changes
+   - Prediction: Refactoring needed
+
+2. **src/models/user.ts** (65% confidence)
+   - Pattern: Quarterly schema updates
+   - Last change: 85 days ago
+   - Prediction: Due for update
+
+3. **tests/integration/** (60% confidence)
+   - Pattern: Test updates lag feature changes
+   - Pending: 12 untested features
+   - Prediction: Test sprint coming
+```
+</commands>
+
+<output_format>
+Responses should be:
+- **Contextual**: Answer the actual question, not just dump data
+- **Temporal**: Show timelines, not just snapshots
+- **Causal**: Link changes to reasons when possible
+- **Actionable**: Suggest what to do with the information
+
+Use visual timelines for evolution:
+```
+├── Date: Event
+│   └── Context/reason
+```
+
+Use tables for comparisons:
+```
+| Metric | Then | Now | Δ |
+```
+
+Use risk indicators:
+- 🔴 High risk/volatility
+- 🟠 Medium risk
+- 🟡 Low risk
+- 🟢 Stable
+</output_format>
+
+<success_criteria>
+- [ ] Parses natural language history queries
+- [ ] Builds timelines from git history
+- [ ] Extracts decision context from commits/PRs
+- [ ] Identifies hotspots and stability patterns
+- [ ] Makes predictions based on evolution
+- [ ] Links to decision graph when available
+- [ ] Provides actionable insights
+</success_criteria>

package/commands/gywd/impact.md

@@ -0,0 +1,317 @@
+---
+name: GYWD:impact
+description: Reality integration - connect code to real-world outcomes
+argument-hint: "[file/function/feature] [--metrics] [--cost] [--incidents]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - Write
+  - WebFetch
+---
+
+<objective>
+Connect code to its real-world impact.
+
+Current AI has no concept of production reality. It generates code in a vacuum.
+
+Reality-Grounded Development links:
+- Code → Production metrics
+- Features → Business outcomes
+- Architecture → Infrastructure costs
+- Code paths → Incident history
+
+Decisions become informed by reality, not just code aesthetics.
+</objective>
+
+<philosophy>
+Code exists to produce outcomes.
+
+A function that runs 1M times/day matters more than one that runs once/month.
+A feature that drives 20% of revenue deserves more attention.
+An endpoint that caused 3 outages needs more care.
+
+Without this context, all code looks equally important.
+With it, priorities become obvious.
+</philosophy>
+
+<reference>
+See `.planning/config.json` for data source configuration and integration setup.
+</reference>
+
+<data_sources>
+## Reality Data Sources
+
+### Production Metrics
+- Request volumes per endpoint
+- Error rates per function
+- Latency percentiles
+- Resource consumption
+
+Integration points:
+- Datadog, New Relic, Prometheus
+- Application logs
+- APM traces
+
+### Business Metrics
+- Feature → Revenue correlation
+- User engagement by feature
+- Conversion impact
+- Retention correlation
+
+Integration points:
+- Analytics platforms (Amplitude, Mixpanel)
+- Business dashboards
+- A/B test results
+
+### Cost Data
+- Compute costs by service
+- Storage costs by table
+- Network costs by endpoint
+- Third-party API costs
+
+Integration points:
+- AWS Cost Explorer
+- Cloud billing APIs
+- Vendor invoices
+
+### Incident History
+- Outages linked to code changes
+- Error spikes by file
+- On-call pages by service
+- Post-mortems by feature
+
+Integration points:
+- PagerDuty, Opsgenie
+- Incident management systems
+- Post-mortem databases
+</data_sources>
+
+<commands>
+## Subcommands
+
+### /gywd:impact <target>
+Show impact profile for file, function, or feature.
+
+```markdown
+## Impact Profile: src/api/checkout.ts
+
+### Production Metrics
+| Metric | Value | Trend |
+|--------|-------|-------|
+| Requests/day | 47,000 | ↑ 12% |
+| Error rate | 0.3% | → stable |
+| P50 latency | 120ms | → stable |
+| P99 latency | 890ms | ↓ improved |
+
+### Business Impact
+- **Revenue attribution**: 34% of daily revenue
+- **Conversion impact**: Critical path for purchase
+- **User sessions**: 23% of all sessions touch this
+
+### Cost Profile
+- **Compute**: $340/month (2.1% of total)
+- **Database**: 12% of read queries
+- **External APIs**: $89/month (Stripe calls)
+
+### Incident History
+| Date | Severity | Cause | Duration |
+|------|----------|-------|----------|
+| 2024-01-15 | P1 | Race condition | 45 min |
+| 2023-11-03 | P2 | Timeout spike | 20 min |
+
+### Risk Assessment
+🔴 **High impact surface**: Outage here affects revenue
+🟠 **Moderate stability**: 2 incidents in 6 months
+🟢 **Good performance**: Latency within SLO
+
+### Recommendations
+1. Add circuit breaker (high impact, no protection)
+2. Increase test coverage (currently 62%)
+3. Consider caching (high volume, stable data)
+```
+
+### /gywd:impact --metrics
+Show production metrics across codebase.
+
+```markdown
+## Production Metrics Overview
+
+### Top Traffic (Requests/Day)
+| Endpoint | Requests | Errors | P99 |
+|----------|----------|--------|-----|
+| GET /api/products | 892K | 0.1% | 45ms |
+| POST /api/cart | 234K | 0.2% | 120ms |
+| POST /api/checkout | 47K | 0.3% | 890ms |
+| GET /api/user | 1.2M | 0.05% | 30ms |
+
+### Error Hotspots
+| File | Error Rate | Volume | Trend |
+|------|------------|--------|-------|
+| src/services/payment.ts | 1.2% | 12K/day | ↑ |
+| src/api/orders.ts | 0.8% | 89K/day | → |
+| src/utils/shipping.ts | 0.6% | 34K/day | ↓ |
+
+### Performance Concerns
+| Endpoint | P99 | SLO | Status |
+|----------|-----|-----|--------|
+| POST /api/search | 2.3s | 1s | 🔴 Violation |
+| GET /api/recommendations | 1.8s | 2s | 🟡 Warning |
+```
+
+### /gywd:impact --cost
+Show infrastructure costs by code area.
+
+```markdown
+## Cost Attribution
+
+**Total Monthly**: $12,400
+
+### By Service
+| Service | Monthly | % | Trend |
+|---------|---------|---|-------|
+| API Server | $4,200 | 34% | ↑ |
+| Database | $3,100 | 25% | → |
+| Cache (Redis) | $890 | 7% | → |
+| Storage (S3) | $2,100 | 17% | ↑ |
+| CDN | $1,200 | 10% | → |
+| External APIs | $910 | 7% | ↓ |
+
+### Cost Drivers
+1. **Image processing** (S3 + compute): $2,800/month
+   - Opportunity: Optimize before upload, save ~40%
+
+2. **Search indexing** (compute): $1,200/month
+   - Opportunity: Batch updates, save ~30%
+
+3. **Payment retries** (Stripe API): $340/month
+   - Opportunity: Better retry logic, save ~50%
+
+### Cost Anomalies
+⚠️ Database reads up 45% but traffic up only 12%
+   Likely cause: Missing index or N+1 query
+```
+
+### /gywd:impact --incidents
+Show incident history and patterns.
+
+```markdown
+## Incident Analysis
+
+### Last 6 Months
+| Severity | Count | MTTR | Trend |
+|----------|-------|------|-------|
+| P1 (Critical) | 2 | 52 min | → |
+| P2 (Major) | 7 | 23 min | ↓ |
+| P3 (Minor) | 15 | 45 min | → |
+
+### By Code Area
+| Area | Incidents | Last | Risk |
+|------|-----------|------|------|
+| src/api/checkout/ | 4 | 2 weeks | 🔴 High |
+| src/services/payment/ | 3 | 1 month | 🟠 Medium |
+| src/api/orders/ | 2 | 3 months | 🟡 Low |
+
+### Root Cause Patterns
+| Pattern | Count | Example |
+|---------|-------|---------|
+| Race condition | 3 | Concurrent cart updates |
+| External service timeout | 3 | Stripe API latency |
+| Database deadlock | 2 | Order + inventory lock |
+| Memory exhaustion | 1 | Large export without streaming |
+
+### Recommendations
+1. **Add timeout handling** to all external calls
+2. **Implement optimistic locking** for cart operations
+3. **Add circuit breakers** to payment service
+```
+</commands>
+
+<integration>
+## How Impact Integrates
+
+### During Planning
+```markdown
+Planning Phase 4: Checkout Optimization
+
+Impact context loaded:
+- 47K requests/day (high impact changes)
+- 2 P1 incidents in area (proceed carefully)
+- $340/month in compute (optimization opportunity)
+
+Recommendations:
+- Add comprehensive tests before changes
+- Implement feature flag for gradual rollout
+- Have rollback plan ready
+```
+
+### During Review
+```markdown
+/gywd:challenge src/api/checkout.ts
+
+Additional context from Impact:
+- This file is in critical revenue path
+- Last change caused P2 incident
+- Suggest extra scrutiny on error paths
+```
+
+### During Decisions
+```markdown
+Decision: Add caching to product API
+
+Impact analysis:
+- Current: 892K requests/day at $0.0001/request
+- With cache: ~70% cache hit expected
+- Savings: ~$200/month
+- Risk: Stale data, complexity
+
+Recommendation: Proceed with 1-hour TTL
+```
+</integration>
+
+<configuration>
+## Setup
+
+Configure data sources in `.planning/config.json`:
+
+```json
+{
+  "impact": {
+    "metrics": {
+      "provider": "datadog",
+      "api_key_env": "DD_API_KEY",
+      "service_tag": "myapp"
+    },
+    "costs": {
+      "provider": "aws",
+      "profile": "production"
+    },
+    "incidents": {
+      "provider": "pagerduty",
+      "api_key_env": "PD_API_KEY"
+    },
+    "analytics": {
+      "provider": "amplitude",
+      "api_key_env": "AMPLITUDE_KEY"
+    }
+  }
+}
+```
+
+If no integrations configured, falls back to:
+- Git history analysis
+- Manual annotations
+- Estimated impact from code analysis
+</configuration>
+
+<success_criteria>
+- [ ] Retrieves production metrics per endpoint/file
+- [ ] Shows business impact attribution
+- [ ] Displays cost breakdown by code area
+- [ ] Surfaces incident history
+- [ ] Identifies patterns and anomalies
+- [ ] Integrates with planning and review
+- [ ] Falls back gracefully without integrations
+</success_criteria>

package/commands/gywd/init.md

@@ -0,0 +1,95 @@
+---
+name: GYWD:init
+description: Quick project initialization with minimal questions
+argument-hint: "[project-name] [optional: --type greenfield|brownfield]"
+---
+
+<objective>
+Fast-track project initialization for users who know what they want.
+
+Unlike /gywd:new-project which asks many questions, /gywd:init gets you started quickly with sensible defaults.
+</objective>
+
+<context>
+This is the "I just want to start coding" option. Use when:
+- You have a clear idea already
+- You want to skip extensive questioning
+- You'll fill in details as you go
+</context>
+
+<process>
+1. Parse arguments:
+   - `$ARGUMENTS` may contain: project name, --type flag
+   - Default type: auto-detect (brownfield if code exists, greenfield if empty)
+
+2. If brownfield detected and no codebase map exists:
+   - Ask: "Existing code detected. Map codebase first? [Y/n]"
+   - If yes: Run /gywd:map-codebase, then continue
+   - If no: Continue without mapping
+
+3. Create minimal PROJECT.md:
+   ```markdown
+   # PROJECT: {name}
+
+   ## What This Is
+   {One-line description from user or "To be defined"}
+
+   ## Core Value
+   To be defined during development.
+
+   ## Requirements
+   - [ ] To be captured as development progresses
+
+   ## Constraints
+   None defined yet.
+
+   ---
+   *Quick-initialized. Expand as needed.*
+   ```
+
+4. Create config.json with defaults:
+   ```json
+   {
+     "mode": "interactive",
+     "planning_depth": "standard"
+   }
+   ```
+
+5. Initialize git if not already initialized
+
+6. Commit initialization files
+
+7. Output:
+   ```
+   ✓ Project initialized: {name}
+
+   Next steps:
+   - /gywd:create-roadmap - Plan your phases
+   - Edit .planning/PROJECT.md - Add details anytime
+   ```
+</process>
+
+<examples>
+Quick init with name:
+```
+/gywd:init my-saas-app
+```
+
+Force greenfield (ignore existing code):
+```
+/gywd:init api-service --type greenfield
+```
+
+Force brownfield mapping:
+```
+/gywd:init legacy-app --type brownfield
+```
+</examples>
+
+<success_criteria>
+- [ ] PROJECT.md created with minimal content
+- [ ] config.json created with defaults
+- [ ] Git initialized (if needed)
+- [ ] User knows next step
+- [ ] Total time: under 30 seconds
+</success_criteria>