@rosetears/aili-pi 0.1.0

package/skills/fullstack-dev/references/release-checklist.md

@@ -0,0 +1,278 @@
+# Release & Acceptance Checklist
+
+6-gate release checklist for backend and full-stack applications. Prevents "it works on my machine" and "we forgot to check X" failures.
+
+**Iron Law: NO RELEASE WITHOUT ALL GATES PASSING.**
+
+---
+
+## Release Gates Overview
+
+```
+Feature Complete
+    ↓
+Gate 1: Functional Acceptance        → Does it do what it should?
+    ↓
+Gate 2: Non-Functional Acceptance    → Is it fast, reliable, observable?
+    ↓
+Gate 3: Security Review              → Is it safe?
+    ↓
+Gate 4: Deployment Readiness         → Can we deploy and rollback safely?
+    ↓
+Gate 5: Release Execution            → Deploy with canary + monitoring
+    ↓
+Gate 6: Post-Release Validation      → Did it actually work in production?
+```
+
+---
+
+## Gate 1: Functional Acceptance
+
+**Question: Does it do what the requirements say?**
+
+- [ ] All acceptance criteria from ticket/PRD have passing tests
+- [ ] Happy path works end-to-end
+- [ ] Edge cases tested (empty inputs, max lengths, Unicode)
+- [ ] Error cases tested (invalid input, not found, timeout)
+- [ ] Data integrity verified (CRUD cycle produces correct state)
+- [ ] Backward compatibility confirmed (existing clients not broken)
+- [ ] API contract matches OpenAPI spec
+- [ ] Idempotency verified (retries don't create duplicates)
+
+### Evidence Template
+
+| Requirement | Test | Status | Notes |
+|-------------|------|--------|-------|
+| User can create order | `orders.api.test:creates order` | ✅ PASS | |
+| Empty cart → error | `orders.api.test:rejects empty` | ✅ PASS | |
+| Payment failure handled | `payments.test:handles decline` | ✅ PASS | |
+
+---
+
+## Gate 2: Non-Functional Acceptance
+
+**Question: Is it fast, reliable, and observable?**
+
+### Performance
+
+- [ ] Response time within budget (p95 < ___ms) — measured, not assumed
+- [ ] No N+1 queries (checked with query logging)
+- [ ] New queries use indexes (`EXPLAIN ANALYZE`)
+- [ ] Pagination works on large datasets
+- [ ] Caching effective (hit rate > 80%)
+- [ ] Connection pool healthy under load
+
+### Reliability
+
+- [ ] Graceful degradation when dependencies fail (circuit breaker)
+- [ ] Retry logic works for transient failures
+- [ ] All external calls have timeouts
+- [ ] Rate limiting returns 429 correctly
+- [ ] Health check endpoints verified (`/health`, `/ready`)
+
+### Observability
+
+- [ ] Structured logging with request ID (not `console.log`)
+- [ ] Metrics exposed (request count, latency, error rate)
+- [ ] Alerts configured (error spike, latency spike)
+- [ ] Request tracing works end-to-end
+- [ ] Dashboard updated for new feature
+
+### Evidence
+
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| p95 response | < 500ms | ___ms | ✅/❌ |
+| p99 response | < 1000ms | ___ms | ✅/❌ |
+| Error rate (load) | < 0.1% | ___% | ✅/❌ |
+| Throughput | > ___ RPS | ___ RPS | ✅/❌ |
+
+---
+
+## Gate 3: Security Review
+
+**Question: Does this introduce vulnerabilities?**
+
+### Input & Output
+
+- [ ] All input validated server-side (never trust client)
+- [ ] SQL injection prevented (parameterized queries only)
+- [ ] XSS prevented (output encoding)
+- [ ] File upload validated (type, size, name sanitized)
+- [ ] Rate limiting on sensitive endpoints (login, reset, APIs)
+
+### Auth & Data
+
+- [ ] Protected endpoints require valid credentials
+- [ ] Users can only access their own resources
+- [ ] Admin routes require admin role
+- [ ] Tokens expire (short-lived access + refresh)
+- [ ] Passwords hashed (bcrypt/argon2, not MD5/SHA)
+- [ ] Sensitive data not logged (passwords, tokens, PII)
+- [ ] Secrets in env vars (not hardcoded)
+- [ ] Error messages don't leak internals
+
+### Dependencies
+
+- [ ] No known vulnerabilities (`npm audit` / `pip audit` / `govulncheck`)
+- [ ] Dependencies pinned in lockfile
+- [ ] Unused dependencies removed
+
+---
+
+## Gate 4: Deployment Readiness
+
+**Question: Can we deploy safely and roll back if needed?**
+
+### Code
+
+- [ ] All tests pass in CI (not "it passed locally")
+- [ ] Linter clean, build succeeds
+- [ ] Code reviewed and approved
+- [ ] No unresolved TODO/FIXME/HACK
+
+### Database
+
+- [ ] Migration tested on staging with production-like data
+- [ ] Down migration works (tested!)
+- [ ] Migration is non-destructive (additive only)
+- [ ] Migration timing estimated on production data size
+- [ ] Backfill plan documented (if needed)
+
+### Configuration
+
+- [ ] New env vars documented in `.env.example`
+- [ ] Env vars set in staging and verified
+- [ ] Env vars set in production
+- [ ] Feature flags configured (if applicable)
+
+### Rollback Plan Template
+
+```markdown
+## Rollback Plan: [Feature]
+
+### When to rollback
+- Error rate > 1% sustained 5 minutes
+- p99 latency > 3000ms sustained 10 minutes
+- Critical business function broken
+
+### Steps
+1. Revert deploy: [command]
+2. Rollback migration (if applied): [command]
+3. Invalidate cache: [command]
+4. Notify team: #incidents channel
+5. Verify rollback: [verification steps]
+
+### Estimated time: [X minutes]
+### Data recovery: [procedure if data was modified]
+```
+
+---
+
+## Gate 5: Release Execution
+
+### Deployment Sequence
+
+```
+1. 📢 ANNOUNCE in release channel
+
+2. 🗄️ DATABASE — Apply migration
+   - Run migration
+   - Verify completion
+   - Check data integrity
+
+3. 🚀 DEPLOY — Roll out code
+   - Canary first (10% traffic)
+   - Monitor 5 minutes
+   - If OK → 50% → monitor → 100%
+   - If NOT OK → STOP immediately
+
+4. 🔍 SMOKE TEST
+   - Health check → 200
+   - Login works
+   - Core operation works
+   - No error spikes
+
+5. ✅ ANNOUNCE "Release complete. Monitoring 30 min."
+```
+
+### Canary Decision Table
+
+| Metric | Baseline | Canary OK | STOP | ROLLBACK |
+|--------|----------|-----------|------|----------|
+| Error rate | 0.05% | < 0.1% | 0.5% | > 1% |
+| p95 latency | 300ms | < 500ms | 700ms | > 1000ms |
+
+---
+
+## Gate 6: Post-Release Validation
+
+### Immediate (0-30 min)
+
+- [ ] Health checks green on all instances
+- [ ] Error rate within normal range
+- [ ] Latency normal (p95, p99)
+- [ ] Core user journey manually tested
+- [ ] Logs clean — no unexpected errors
+- [ ] Alerts silent
+
+### Short-term (1-24 hours)
+
+- [ ] No customer complaints
+- [ ] Business metrics stable (conversion, revenue, signups)
+- [ ] Memory/CPU stable (no creeping usage)
+- [ ] Queue backlogs clear
+- [ ] Database performance stable
+
+### Post-Release Report Template
+
+```markdown
+## Release Report: [Feature]
+- Deployed: [timestamp] by @[engineer]
+- Duration: [minutes]
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Health checks | ✅ | All healthy |
+| Error rate | ✅ | 0.03% (baseline: 0.05%) |
+| p95 latency | ✅ | 310ms (baseline: 300ms) |
+| Core flow | ✅ | Order creation verified |
+
+Issues found: None / [details]
+Rollback used: No / Yes: [reason]
+```
+
+---
+
+## Release Readiness Score
+
+Score each gate **0-2**: (0 = not checked, 1 = partially, 2 = fully verified with evidence)
+
+| Gate | Score |
+|------|-------|
+| 1. Functional Acceptance | /2 |
+| 2. Non-Functional Acceptance | /2 |
+| 3. Security Review | /2 |
+| 4. Deployment Readiness | /2 |
+| 5. Release Execution Plan | /2 |
+| 6. Post-Release Validation Plan | /2 |
+| **Total** | **/12** |
+
+**Decision:**
+- **12/12** → Ship it ✅
+- **10-11** → Ship with documented exceptions + owner assigned
+- **< 10** → Do NOT release. Fix gaps first.
+
+---
+
+## Common Rationalizations
+
+| ❌ Excuse | ✅ Reality |
+|----------|-----------|
+| "It's a small change" | Small changes cause outages every day |
+| "We tested locally" | Local ≠ production |
+| "We'll fix it if it breaks" | You'll fix it at 3 AM. Prevent now. |
+| "Deadline is today" | Broken code costs more than late code |
+| "CI passed" | CI doesn't check everything. Run the checklist. |
+| "We can always rollback" | Only if you planned and tested rollback |
+| "We did this last time fine" | Survivorship bias. Checklist every time. |

package/skills/fullstack-dev/references/technology-selection.md

@@ -0,0 +1,254 @@
+# Technology Selection Framework
+
+Structured decision framework for backend and full-stack technology choices. Prevents analysis paralysis while ensuring rigorous evaluation.
+
+**Iron Law: NO TECHNOLOGY CHOICE WITHOUT EXPLICIT TRADE-OFF ANALYSIS.**
+
+"I like it" and "it's trending" are not engineering arguments.
+
+---
+
+## Phase 1: Requirements Before Technology
+
+### Non-Functional Requirements (Quantify!)
+
+| Dimension | Question | Bad Answer | Good Answer |
+|-----------|----------|-----------|-------------|
+| Scale | How many concurrent users? | "Lots" | "1K concurrent, 500 RPS peak" |
+| Latency | Acceptable p99 response time? | "Fast" | "< 200ms API, < 2s reports" |
+| Availability | Required uptime? | "Always up" | "99.9% (8.7h downtime/year)" |
+| Data volume | Expected storage growth? | "A lot" | "100GB/year, 10M rows" |
+| Consistency | Strong vs eventual? | "Consistent" | "Strong for payments, eventual for feeds" |
+| Compliance | Regulatory? | "Some" | "GDPR data residency EU, SOC 2 Type II" |
+
+### Team Constraints
+
+- Team size and seniority level
+- What the team already knows well
+- Can you hire for this stack? (check job market)
+- Timeline pressure (days vs months to production)
+- Budget for licenses, infrastructure, training
+
+---
+
+## Phase 2: Evaluation Matrix
+
+Score each option 1-5 on weighted criteria:
+
+| Criterion | Weight | Option A | Option B | Option C |
+|-----------|--------|----------|----------|----------|
+| Meets functional requirements | 5× | _ | _ | _ |
+| Meets non-functional requirements | 5× | _ | _ | _ |
+| Team expertise / learning curve | 4× | _ | _ | _ |
+| Ecosystem maturity (libs, tools) | 3× | _ | _ | _ |
+| Community & long-term viability | 3× | _ | _ | _ |
+| Operational complexity | 3× | _ | _ | _ |
+| Hiring pool availability | 2× | _ | _ | _ |
+| Cost (license + infra + training) | 2× | _ | _ | _ |
+| **Weighted Total** | | _ | _ | _ |
+
+**Rules:**
+- Any option scoring **1 on a 5× criterion** → automatically disqualified
+- Options within **10%** of each other → choose what team knows best
+- Options within **15%** → run a **time-boxed PoC** (2-5 days max)
+
+---
+
+## Phase 3: Decision Trees
+
+### Backend Language / Framework
+
+```
+What type of project?
+│
+├─ REST/GraphQL API, rapid development
+│   ├─ Team knows TypeScript → Node.js
+│   │   ├─ Full-featured, enterprise patterns → NestJS
+│   │   ├─ Lightweight, flexible → Fastify / Hono / Express
+│   │   └─ Full-stack with React → Next.js API routes
+│   ├─ Team knows Python
+│   │   ├─ High-perf async API → FastAPI
+│   │   ├─ Full-stack, admin-heavy → Django
+│   │   └─ Lightweight → Flask / Litestar
+│   └─ Team knows Java/Kotlin
+│       ├─ Enterprise, large team → Spring Boot
+│       └─ Lightweight, fast startup → Quarkus / Ktor
+│
+├─ High concurrency, systems-level
+│   ├─ Microservices, network → Go
+│   ├─ Extreme perf, safety → Rust (Axum / Actix)
+│   └─ Fault tolerance → Elixir (Phoenix)
+│
+├─ Real-time (WebSocket, streaming)
+│   ├─ Node.js ecosystem → Socket.io / ws
+│   ├─ Scalable pub/sub → Elixir Phoenix
+│   └─ Low-latency → Go / Rust
+│
+└─ ML / data-intensive
+    └─ Python (FastAPI + ML libs)
+```
+
+### Database
+
+```
+What data model?
+│
+├─ Structured, relational, ACID
+│   ├─ General purpose → PostgreSQL ← DEFAULT CHOICE
+│   ├─ Read-heavy, MySQL ecosystem → MySQL / MariaDB
+│   └─ Embedded / serverless edge → SQLite / Turso / D1
+│
+├─ Semi-structured, flexible schema
+│   ├─ Document-oriented → MongoDB
+│   ├─ Serverless document → DynamoDB / Firestore
+│   └─ Search-heavy → Elasticsearch / OpenSearch
+│
+├─ Key-value / cache
+│   ├─ In-memory + data structures → Redis / Valkey
+│   └─ Planet-scale KV → DynamoDB / Cassandra
+│
+├─ Time-series → TimescaleDB / ClickHouse / InfluxDB
+├─ Graph → Neo4j / Apache AGE (Postgres extension)
+└─ Vector (AI embeddings) → pgvector / Pinecone / Qdrant
+```
+
+**Default:** Start with PostgreSQL. It handles 80% of use cases.
+
+### Caching Strategy
+
+| Pattern | Technology | When |
+|---------|-----------|------|
+| Application cache | Redis / Valkey | Sessions, frequent reads, rate limiting |
+| HTTP cache | CDN (Cloudflare/Vercel) | Static assets, public API responses |
+| Query cache | Materialized views | Complex aggregations, dashboards |
+| In-process cache | LRU (in-memory) | Config, small lookup tables |
+| Edge cache | Cloudflare KV / Vercel KV | Global low-latency reads |
+
+### Message Queue / Event Streaming
+
+| Pattern | Technology | When |
+|---------|-----------|------|
+| Task queue (background jobs) | BullMQ / Celery / SQS | Email, exports, payments |
+| Event streaming (replay, audit) | Kafka / Redpanda | Event sourcing, real-time pipelines |
+| Lightweight pub/sub | Redis Streams / NATS | Simple notifications, broadcasting |
+| Request-reply (sync over async) | NATS / RabbitMQ RPC | Internal service calls |
+
+### Hosting / Deployment
+
+| Model | Technology | When |
+|-------|-----------|------|
+| Serverless (auto-scale) | Vercel / Cloudflare Workers / Lambda | Variable traffic, pay-per-use |
+| Container (predictable) | Cloud Run / Render / Railway / Fly.io | Steady traffic, simple ops |
+| Kubernetes (large scale) | EKS / GKE / AKS | 10+ services, team has K8s expertise |
+| VPS (full control) | DigitalOcean / Hetzner / EC2 | Predictable workload, cost-sensitive |
+
+---
+
+## Phase 4: Decision Documentation
+
+### ADR (Architecture Decision Record) Template
+
+```markdown
+# ADR-{NNN}: {Title}
+
+## Status: Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
+
+## Context
+What problem are we solving? What forces are at play?
+
+## Decision
+What did we choose and why?
+
+## Evaluation
+| Criterion | Weight | Chosen | Runner-up |
+|-----------|--------|--------|-----------|
+
+## Consequences
+- Positive: ...
+- Negative: ...
+- Risks: ...
+
+## Alternatives Rejected
+- Option B: rejected because...
+- Option C: rejected because...
+```
+
+---
+
+## Common Stack Templates
+
+### A: Startup / MVP (Speed)
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Language | TypeScript | One language front + back |
+| Framework | Next.js (full-stack) or NestJS (API) | Fast iteration |
+| Database | PostgreSQL (Supabase / Neon) | Managed, generous free tier |
+| Auth | Better Auth / Clerk | No auth code to maintain |
+| Cache | Redis (Upstash) | Serverless-friendly |
+| Hosting | Vercel / Railway | Zero-config deploys |
+
+### B: SaaS / Business App (Balance)
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Language | TypeScript or Python | Team preference |
+| Framework | NestJS or FastAPI | Structured, testable |
+| Database | PostgreSQL | Reliable, feature-rich |
+| Queue | BullMQ (Redis) | Simple background jobs |
+| Auth | OAuth 2.0 + JWT | Standard, flexible |
+| Hosting | AWS ECS / Cloud Run | Scalable containers |
+| Monitoring | Datadog / Grafana + Prometheus | Full observability |
+
+### C: High-Performance (Scale)
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Language | Go or Rust | Max throughput, low latency |
+| Database | PostgreSQL + Redis + ClickHouse | OLTP + cache + analytics |
+| Queue | Kafka / Redpanda | High-throughput streaming |
+| Hosting | Kubernetes (EKS/GKE) | Fine-grained scaling |
+| Monitoring | Prometheus + Grafana + Jaeger | Metrics + tracing |
+
+### D: AI / ML Application
+
+| Layer | Choice | Why |
+|-------|--------|-----|
+| Language | Python (API) + TypeScript (frontend) | ML libs + modern UI |
+| Framework | FastAPI + Next.js | Async + SSR |
+| Database | PostgreSQL + pgvector | Relational + embeddings |
+| Queue | Celery + Redis | ML job processing |
+| Hosting | Modal / AWS GPU / Replicate | GPU access |
+
+---
+
+## Anti-Patterns
+
+| # | ❌ Don't | ✅ Do Instead |
+|---|---------|--------------|
+| 1 | "X is trending on HN" | Evaluate against YOUR requirements |
+| 2 | Resume-Driven Development | Choose what team can maintain |
+| 3 | "Must scale to 1M users" (day 1) | Build for 10× current need, not 1000× |
+| 4 | Evaluate for weeks | Time-box to 3-5 days, then decide |
+| 5 | No decision documentation | Write ADR for every major choice |
+| 6 | Ignore operational cost | Include deploy, monitor, debug cost |
+| 7 | "We'll rewrite later" | Assume you won't. Choose carefully. |
+| 8 | Microservices by default | Start monolith, extract when needed |
+| 9 | Different DB per service (day 1) | One database, split when justified |
+| 10 | "It worked at Google" | You're not Google. Scale to YOUR context. |
+
+---
+
+## Common Issues
+
+### Issue 1: "Team can't agree on a framework"
+
+**Fix:** Time-box to 3 days. Fill the evaluation matrix. If scores within 10%, pick what the majority knows. Document in ADR. Move on.
+
+### Issue 2: "We picked X but it doesn't fit"
+
+**Fix:** Sunk cost fallacy check. If < 2 weeks invested, switch now. If > 2 weeks, document pain points and plan phased migration.
+
+### Issue 3: "Do we need microservices?"
+
+**Fix:** Almost certainly no. Start with a well-structured monolith. Extract to services only when: (a) different scaling needs, (b) different team ownership, (c) different deployment cadence.