shapeup-sdlc 1.6.2

package/skills/ba-pitch-analyzer/assets/templates/_index.tmpl.md

@@ -0,0 +1,84 @@
+---
+type: pitch
+feature: FEATURE_SLUG
+appetite: "X weeks"
+status: draft
+bounded_context: CONTEXT
+entities: []
+tags: []
+skill_version: "2.5"
+audit_rules_version: "2.5"
+---
+
+# Pitch: FEATURE TITLE
+
+## Problem
+<!-- 2-3 sentences: what user pain or opportunity drives this feature -->
+
+## Appetite
+**X weeks** — if scope grows beyond this, cut features, do not extend timeline.
+
+## Boundaries
+
+### In Scope
+- ...
+
+### Non-Go
+- ...
+
+## Solution Elements
+
+### Breadboarding
+<!-- Text-based flow showing the key interaction path, no images needed -->
+```
+[Screen A] ──action──► [Screen B] ──action──► [Outcome]
+               │
+           context/data
+```
+
+### Key Interactions
+<!-- Fat marker level — major UI moments, not detailed specs -->
+1. ...
+2. ...
+
+## Rabbit Holes (Risks)
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| ... | high/med/low | ... |
+
+## Document Map
+
+| Document | Type | Status |
+|----------|------|--------|
+| [[assess-report]] | Assess Report | ⬜ draft |
+| [[domain-model]] | DDD Model | ⬜ draft |
+| [[ux-behavior]] | UX Spec | ⬜ draft |
+| [[usecases/_index]] | Use Cases | ⬜ draft |
+| [[integration]] | Integration Map | ⬜ draft |
+| [[scope-summary]] | Scope Summary | ⬜ draft |
+| [[synthesis]] | Health Dashboard + Traceability + Risk + Dependency | ⬜ draft |
+| [[feedback]] | Post-Sprint Feedback | ⬜ pending |
+
+---
+
+## Audit Report
+
+*Generated from spec-lint.mjs output — do not edit manually.*
+*skill_version: 2.1 | audit_rules_version: 2.1*
+
+### Score Summary
+
+| Layer | Weight | Raw Score | Weighted |
+|-------|--------|-----------|---------|
+| L0 Input Quality | 10% | —/100 | — |
+| L1 Generation Complete | 20% | —/100 | — |
+| L2 Document Quality | 30% | —/100 | — |
+| L3 Execution Readiness | 40% | —/100 | — |
+| **TOTAL** | | | **—/100** |
+
+### Execution Gate
+⬜ *Pending audit*
+
+### Issues Found
+⬜ *Pending audit*

package/skills/ba-pitch-analyzer/assets/templates/api-feasibility.tmpl.md

@@ -0,0 +1,65 @@
+---
+type: api-feasibility
+feature: "[feature-slug]"
+status: draft
+skill_version: "2.3"
+---
+
+# API Feasibility Report — [feature-slug]
+
+*Generated by Phase 1b. Each investigation block must be resolved before its
+dependent implementation tasks can proceed.*
+
+---
+
+## Detected Third-Party Dependencies
+
+| # | Service | Capability Claimed | Status | SPIKE Task |
+|---|---------|-------------------|--------|------------|
+| API-01 | [ServiceName] | [What pitch claims this API can do] | ❓ UNVERIFIED | [[TASK-001-spike-[api]]] |
+
+---
+
+## Investigations Required
+
+### [API-01] [ServiceName] — [Capability Summary]
+
+**Capability Claimed:**
+Pitch assumes [ServiceName] API/SDK can [specific operation].
+Specifically: [quote or paraphrase relevant pitch sentence].
+
+**Questions to Answer:**
+- [ ] Does [ServiceName] support [operation] via REST API or SDK?
+- [ ] What is the exact input format accepted? (HTML, JSON, design tokens?)
+- [ ] What does the response body look like on success? (field names, types)
+- [ ] What auth model is required? (API Key, OAuth, Service Account, Bearer JWT)
+- [ ] Is there a sandbox / staging environment for testing without billing?
+- [ ] What are the rate limits and pricing implications?
+- [ ] Are there known breaking changes or deprecation notices?
+
+**Verification Sources:**
+- Primary (official): [URL — to be found during SPIKE]
+- Secondary (community): GitHub issues / Discord / forum threads for [ServiceName]
+
+**Fallback Scope Impact:**
+
+| Scenario | Scope Change | Effort Delta |
+|----------|-------------|--------------|
+| Fully supported | No change | — |
+| Partially supported | [Describe workaround] | +[N]h |
+| Not supported | [Describe alternative or de-scope] | [TBD with PO] |
+
+**Dependent Tasks:**
+<!-- List all tasks blocked until this investigation is complete -->
+- [[TASK-NNN]] — [reason blocked]
+- [[TASK-NNN]] — [reason blocked]
+
+**Decision Gate:**
+- All questions answered + capability confirmed → update `contracts/[repo].contract.md`, remove ⏳ TBD fields, notify SPIKE complete
+- Not answerable within SPIKE time_box → escalate to PO with fallback options above
+
+**Resolution:** *(filled post-SPIKE)*
+> Status: [CONFIRMED / PARTIAL / NOT SUPPORTED]
+> Source: [URL with section]
+> Date resolved: [YYYY-MM-DD]
+> Resolved by: [Dev name / handle]

package/skills/ba-pitch-analyzer/assets/templates/assess-report.tmpl.md

@@ -0,0 +1,127 @@
+---
+type: assess-report
+feature: FEATURE_SLUG
+generated_at: YYYY-MM-DD
+pitch_hash: HASH
+skill_version: "2.5"
+l0_preview_score: 0
+codebase_confidence: 0
+recommended_lens: lite | standard
+proceed: go | go+fix | no-go
+multi_context_detected: false
+---
+
+# Assess Report: FEATURE TITLE
+
+> **Read Decision Summary only — open sections below if you need to know why.**
+
+---
+
+## ⚡ Decision Summary
+
+```
+Recommended lens : LENS
+Estimated tokens : ~MIN–MAX tokens
+Estimated cost   : ~$MIN–$MAX
+Input quality    : SCORE/100
+Codebase fit     : CONFIDENCE%
+Proceed?         : PROCEED_STATUS
+```
+
+---
+
+## Input Quality (L0 Preview)
+
+Score: SCORE/100 — STATUS
+
+| Check | Result | Note |
+|-------|--------|------|
+| Appetite stated | ✅ / ❌ | value |
+| In-scope boundaries (≥ 2) | ✅ / ❌ | count found |
+| Non-go list (≥ 1) | ✅ / ❌ | count found |
+| Rabbit hole identified | ✅ / ❌ | — |
+| Rabbit hole has mitigation | ✅ / ❌ | — |
+| Third-party declared (if any) | ✅ / ❌ / N/A | — |
+
+**Fix list** *(only present when proceed = go+fix or no-go):*
+- [ ] [issue] — [actionable suggestion]
+- [ ] [issue] — [actionable suggestion]
+
+---
+
+## Codebase Fit
+
+Confidence: CONFIDENCE%
+
+| Signal | Found | Weight |
+|--------|-------|--------|
+| CLAUDE.md readable | ✅ / ❌ | +25 |
+| Schema pattern (*.schema.ts) | ✅ / ❌ | +25 |
+| Repository layer | ✅ / ❌ | +25 |
+| Monorepo structure clear | ✅ / ❌ | +15 |
+| Test pattern consistent | ✅ / ❌ | +10 |
+
+**Warnings** *(if any):*
+- ⚠️ [what was not found] → [recommendation]
+
+---
+
+## Estimated Output
+
+```
+Lens          : LENS
+Documents     : N files
+Use Cases     : ~N UCs (estimated)
+Tasks         : ~N–N tasks
+SPIKE tasks   : N (third-party APIs detected: [list])
+```
+
+<!-- MULTI-CONTEXT BLOCK — include only when multi_context_detected: true -->
+## ⚠️ Multi-Context Detected
+
+This pitch touches N bounded contexts: [context-a], [context-b], [context-c]
+
+**Option A — Single standard run** *(faster, boundaries may be blurry)*
+```bash
+/ba-pitch-analyzer --lens standard docs/pitch.md
+```
+Estimated tokens: ~N tokens
+
+**Option B — Split + cross-context** *(slower, precise boundaries)*
+```bash
+/ba-pitch-analyzer --lens standard docs/pitch-[context-a].md
+/ba-pitch-analyzer --lens standard docs/pitch-[context-b].md
+/ba-pitch-analyzer --cross-context FEATURE_SLUG \
+    shapeup/[context-a]/spec/ \
+    shapeup/[context-b]/spec/
+```
+Estimated tokens: ~N total (reusable per context)
+
+Choose: **[A]** or **[B]**
+<!-- END MULTI-CONTEXT BLOCK -->
+
+---
+
+## Lens Options
+
+| Lens | Tokens | Cost | Recommended |
+|------|--------|------|-------------|
+| `--lens lite` | ~6,000–8,000 | ~$0.03–$0.04 | [✅ if applicable] |
+| `--lens standard` | ~14,000–22,000 | ~$0.07–$0.11 | [✅ if applicable] |
+| `--cross-context` | ~N | ~$N | [✅ if applicable] |
+
+---
+
+## Next Steps
+
+```bash
+# Proceed with recommended lens
+/ba-pitch-analyzer --lens LENS docs/pitch.md
+
+# Override lens
+/ba-pitch-analyzer --lens lite docs/pitch.md
+/ba-pitch-analyzer --lens standard docs/pitch.md
+
+# Skip assess on next run (pitch already reviewed)
+/ba-pitch-analyzer --lens LENS --skip-assess docs/pitch.md
+```

package/skills/ba-pitch-analyzer/assets/templates/contracts/be-service.contract.tmpl.md

@@ -0,0 +1,62 @@
+---
+type: repository-contract
+source_type: be-service
+feature: "[feature-slug]"
+repository: "[RepoName]"
+service: "[internal service name]"
+status: confirmed        # be-service contracts are verifiable from codebase
+skill_version: "2.3"
+---
+
+# Repository Contract — [RepoName]
+
+## Source Type: `be-service`
+## Endpoint Base: `[apps/api or service URL base]`
+## Auth: `[Bearer JWT (session) / API Key / Service-to-service mTLS]`
+
+---
+
+## Method: [methodName]
+
+### HTTP Request
+
+```
+[POST/GET/PUT/PATCH/DELETE] [/api/v1/path/:param]
+Content-Type: application/json
+Authorization: Bearer [session JWT]
+```
+
+### Request Body
+
+| Field | Type | Validation | Source | Notes |
+|-------|------|-----------|--------|-------|
+| [field1] | string | required, max 255 | UC-[Name].input.[field] | |
+| [field2] | uuid | required | UC-[Name].input.[field] | FK to [Entity] |
+| [field3] | number | min 0 | UC-[Name].input.[field] | VND — integer only, no float |
+
+### Response `201 Created` / `200 OK`
+
+| Field | Type | Invariant | Used By |
+|-------|------|-----------|---------|
+| id | uuid | non-null, server-generated | subsequent requests |
+| [field1] | string | | UX: [state/display] |
+| createdAt | ISO8601 | UTC | UX: timestamp display |
+
+### Error Responses
+
+| HTTP Status | Code | Meaning | UX Action |
+|-------------|------|---------|-----------|
+| 400 | VALIDATION_ERROR | Field-level validation failed | Show per-field inline errors |
+| 401 | UNAUTHORIZED | Session expired or missing | Redirect to login |
+| 403 | FORBIDDEN | Caller lacks [ROLE] permission | Show permission error |
+| 404 | NOT_FOUND | Resource [Entity] not found | Show 404 state |
+| 409 | CONFLICT | [Describe conflict condition] | Show conflict message |
+| 413 | PAYLOAD_TOO_LARGE | Request body exceeds [N]kb | Show size error |
+| 422 | BUSINESS_RULE_VIOLATION | [Describe invariant] | Show business error |
+| 5xx | INTERNAL_ERROR | Server error | Generic error + retry |
+
+---
+
+## Method: [methodName2]
+
+*(repeat block per method)*

package/skills/ba-pitch-analyzer/assets/templates/contracts/offline-storage.contract.tmpl.md

@@ -0,0 +1,92 @@
+---
+type: repository-contract
+source_type: offline-storage
+feature: "[feature-slug]"
+repository: "[RepoName]"
+engine: "[SQLite via Drizzle / AsyncStorage / MMKV / FileSystem]"
+schema_ref: "[[domain-model#[EntityName]]]"
+migration_version: "v[NNN]"
+status: confirmed
+skill_version: "2.3"
+---
+
+# Repository Contract — [RepoName]
+
+## Source Type: `offline-storage`
+## Engine: [SQLite via Drizzle ORM / AsyncStorage / MMKV / FileSystem]
+## Schema Ref: [[domain-model#[EntityName]]]
+## Migration Version: `v[NNN]` — must match domain-model schema version
+
+---
+
+## Storage Schema
+
+### Table / Key: `[table_name or storage_key]`
+
+| Column / Key | Type | Constraint | Migration | Notes |
+|-------------|------|-----------|-----------|-------|
+| id | uuid | PK, NOT NULL | v001_initial | |
+| [field1] | text | NOT NULL | v001_initial | |
+| [field2] | integer | NOT NULL, default 0 | v001_initial | VND — integer only |
+| [field3] | text? | NULL | v002_add_[field] | nullable until [condition] |
+| createdAt | text | NOT NULL, ISO8601 | v001_initial | stored as UTC string |
+| updatedAt | text | NOT NULL | v001_initial | update trigger or app-managed |
+
+---
+
+## Method: [methodName] (Write)
+
+### Write Input
+
+| Field | Type | Required | Source |
+|-------|------|----------|--------|
+| [field1] | string | ✓ | UC-[Name].input.[field] |
+| [field2] | number | ✓ | domain.[Entity].[field] |
+
+### Write Output
+
+| Field | Type | Invariant |
+|-------|------|-----------|
+| id | uuid | server-generated, non-null |
+| [field1] | string | mirrors input |
+
+### Error Cases
+
+| Condition | Error Type | Recovery |
+|-----------|-----------|---------|
+| Disk full | StorageError(QUOTA_EXCEEDED) | Prompt user to free space |
+| Schema mismatch | MigrationError | Run pending migrations |
+| Concurrent write | ConflictError | [last-write-wins / merge strategy] |
+
+---
+
+## Method: [methodName2] (Read)
+
+### Read Output
+
+| Field | Type | Null Behavior |
+|-------|------|--------------|
+| [field1] | string \| null | null when [condition] — caller must handle |
+| [field2] | [Entity][] | empty array [] when no rows — never null |
+
+### Error Cases
+
+| Condition | Error Type | Recovery |
+|-----------|-----------|---------|
+| Record not found | returns `null` — never throws | Caller checks null |
+| DB locked | StorageError(LOCKED) | Retry with backoff |
+
+---
+
+## Conflict Strategy: `[last-write-wins / merge / reject]`
+
+*Describe: when two writes happen concurrently, what is the resolution?*
+
+## Migration Runbook
+
+```sql
+-- v[NNN]: [description]
+ALTER TABLE [table] ADD COLUMN [col] [type] [constraint];
+```
+
+Rollback: `[rollback SQL or "destructive — no rollback"]`

package/skills/ba-pitch-analyzer/assets/templates/contracts/third-party-api.contract.tmpl.md

@@ -0,0 +1,66 @@
+---
+type: repository-contract
+source_type: third-party-api
+feature: "[feature-slug]"
+repository: "[RepoName]"
+service: "[ServiceName]"
+feasibility_ref: "API-[NN]"
+spike_task: "[[TASK-NNN-spike-[api]]]"
+status: speculative      # → confirmed after SPIKE done
+skill_version: "2.3"
+---
+
+# Repository Contract — [RepoName]
+
+## Source Type: `third-party-api`
+## Service: [ServiceName] ([REST API / SDK])
+## Feasibility: ⏳ UNVERIFIED → see [[api-feasibility#API-NN]] + [[TASK-NNN-spike-[api]]]
+
+---
+
+> ⚠️ **SPECULATIVE CONTRACT**
+> Fields marked `⏳ TBD` are derived from pitch assumptions and community references.
+> All `⏳ TBD` entries MUST be confirmed and replaced during [[TASK-NNN-spike-[api]]].
+> Implementation tasks depending on this repository are **blocked** until no `⏳ TBD` remains.
+
+---
+
+## Method: [methodName]
+
+### Request
+
+| Field | Type | Required | Source | Notes |
+|-------|------|----------|--------|-------|
+| [field1] | string | ✓ | UC-[Name].input.[field] | ⏳ TBD — field name unverified |
+| [field2] | string | ✓ | env.[ENV_VAR_NAME] | ⏳ TBD — confirm param name |
+| [field3] | string? | — | session.[claim] | ⏳ TBD — may not be required |
+
+### Response (Success)
+
+| Field | Type | Invariant | Used By | Notes |
+|-------|------|-----------|---------|-------|
+| [field1] | string | ⏳ TBD | [method2].request.[field] | ⏳ TBD — confirm field name |
+| [field2] | enum | ⏳ TBD | UX: [badge/state name] | ⏳ TBD — confirm possible values |
+
+### Error Cases
+
+| Code | HTTP/SDK Error | Retryable | UX Action | Notes |
+|------|---------------|-----------|-----------|-------|
+| UNAUTHORIZED | 401 / AuthError | false | Show: "API key invalid" | ⏳ TBD — confirm error shape |
+| QUOTA_EXCEEDED | 429 / RateLimitError | true | Queue + retry | ⏳ TBD — confirm retry-after header |
+| INVALID_INPUT | 400 / ValidationError | false | Show field error | ⏳ TBD — confirm error body |
+| UNKNOWN | 5xx / NetworkError | true | Generic error + retry | |
+
+---
+
+## Method: [methodName2]
+
+*(repeat block per method)*
+
+---
+
+## Post-SPIKE Update Log
+
+| Field | Old Value | Confirmed Value | Source URL | Updated By | Date |
+|-------|-----------|----------------|------------|------------|------|
+| | | | | | |

package/skills/ba-pitch-analyzer/assets/templates/cross-context/context-map.tmpl.md

@@ -0,0 +1,64 @@
+---
+type: context-map
+feature: FEATURE_SLUG
+skill_version: "2.5"
+contexts: []
+relationships: []
+tags: [cross-context, ddd]
+depends_on: []
+status: draft
+---
+
+# Context Map: FEATURE TITLE
+
+> Maps relationships between bounded contexts involved in this feature.
+> Relationship types follow Evans DDD vocabulary.
+
+---
+
+## Context Diagram
+
+```
+[Context A] ──publishes──► EventName ──────────────► [Context B]
+                                                            │
+[Context C] ──provides──► EntityName ─────────────► [Context A]
+                                                            │
+[Context D] ◄──subscribes── EventName                      │
+       │                                                    │
+       └──publishes──► EventName2 ──────────────────► [Context A]
+```
+
+---
+
+## Relationship Register
+
+| From Context | To Context | Type | Contract |
+|-------------|-----------|------|----------|
+| [Context A] | [Context B] | Customer/Supplier | [[contracts/[repo].contract.md]] |
+| [Context B] | [Context C] | Conformist | [Context C] sets schema |
+| [Context D] | External | Anti-corruption | [[api-feasibility#API-01]] |
+
+**Relationship types:**
+- **Customer/Supplier** — downstream depends on upstream; upstream team sets contract
+- **Conformist** — downstream conforms to upstream schema with no negotiation
+- **Anti-corruption Layer** — downstream wraps upstream behind its own abstraction
+- **Shared Kernel** — both contexts share a subset of domain model (use sparingly)
+- **Published Language** — upstream publishes a well-defined schema; downstream consumes
+
+---
+
+## Context Responsibilities
+
+| Context | Owns | Does NOT Own |
+|---------|------|-------------|
+| [Context A] | [entity list] | [boundary note] |
+| [Context B] | [entity list] | [boundary note] |
+
+---
+
+## Integration Points
+
+| Event / Data | Producer | Consumer(s) | Coupling Risk |
+|-------------|---------|------------|--------------|
+| `EventName` | [Context A] | [Context B], [Context C] | 🔴 high — 2 consumers |
+| `EntityName` | [Context C] | [Context A] | 🟡 medium |

package/skills/ba-pitch-analyzer/assets/templates/cross-context/event-choreography.tmpl.md

@@ -0,0 +1,77 @@
+---
+type: event-choreography
+feature: FEATURE_SLUG
+skill_version: "2.5"
+contexts: []
+events: []
+tags: [cross-context, events]
+depends_on: ["[[_cross-context/context-map]]"]
+status: draft
+---
+
+# Event Choreography: FEATURE TITLE
+
+> Sequence of domain events flowing across bounded contexts.
+> Includes dead-letter and timeout scenarios.
+
+---
+
+## Happy Path Sequence
+
+```
+UC-[Name] triggers:
+
+  [Context A]            [Context B]            [Context C]
+       │                      │                      │
+       │──EventName1──────────►│                      │
+       │                      │──EventName2──────────►│
+       │                      │                      │──SideEffect
+       │◄─────────────────────│                      │
+       │──EventName3           │                      │
+       │                      │                      │
+```
+
+---
+
+## Event Register
+
+| Event | Emitted By | Consumed By | Payload Fields | Schema Ref |
+|-------|-----------|------------|---------------|-----------|
+| `EventName1` | [Context A] :: UC-Name | [Context B] | id, field1, field2 | [[domain-model#Events]] |
+| `EventName2` | [Context B] | [Context C] | id, field1 | [[context-b/domain-model#Events]] |
+
+---
+
+## Failure Scenarios
+
+| Scenario | Trigger | Impact | Recovery Strategy |
+|----------|---------|--------|------------------|
+| `EventName2` never arrives | [Context B] crash | [Context C] stuck in pending | Timeout N min → auto-cancel + emit `EventName2Timeout` |
+| [Context C] rejects `EventName2` | schema mismatch | silent failure | Dead-letter queue → alert → manual replay |
+| Duplicate `EventName1` | retry storm | double-process | Idempotency key on `EventName1.id` |
+
+---
+
+## Timeout Register
+
+| Event | Timeout | Owner Context | Action on Timeout |
+|-------|---------|--------------|------------------|
+| `EventName1` → `EventName2` | N minutes | [Context A] | emit `CancelRequested` |
+| `EventName2` → SideEffect | N minutes | [Context B] | retry × 3 → dead-letter |
+
+---
+
+## Dead-Letter Strategy
+
+```
+Dead-letter queue: [queue-name]
+
+On failure:
+  1. Log event payload + error + context
+  2. Retry: N times with exponential backoff (base: Ns, max: Ns)
+  3. After max retries: move to DLQ
+  4. Alert: [channel/mechanism]
+  5. Manual replay: [command or runbook reference]
+
+User impact: [none / degraded / blocked — describe]
+```