ai-playbook 1.0.0

package/roles/software-developer/authorization/checklists.md

@@ -0,0 +1,21 @@
+# Authorization Checklists
+
+## Design
+
+- [ ] Identify protected resources, actions, actors, and tenant boundaries.
+- [ ] Define policy rules in terms of role, relationship, ownership, or attributes.
+- [ ] Decide where enforcement occurs: handler, service layer, policy engine, or database.
+- [ ] Document admin, delegation, and support-access exceptions.
+
+## Implementation
+
+- [ ] Check authorization after authentication and before side effects.
+- [ ] Use shared policy helpers instead of duplicating one-off checks.
+- [ ] Make failed checks return safe error responses.
+- [ ] Add audit events for permission changes and privileged access.
+
+## Verification
+
+- [ ] Test allowed, denied, cross-tenant, unauthenticated, and stale-permission cases.
+- [ ] Confirm client-provided roles or ownership fields cannot bypass enforcement.
+- [ ] Verify audit logs include actor, target, action, and result.

package/roles/software-developer/authorization/examples.md

@@ -0,0 +1,27 @@
+# Authorization Examples
+
+## Policy Check
+
+```python
+def require_project_access(principal: Principal, project: Project, action: str) -> None:
+    if principal.tenant_id != project.tenant_id:
+        raise Forbidden("cross-tenant access denied")
+
+    if action not in principal.permissions_for(project.id):
+        raise Forbidden("permission denied")
+```
+
+## Audit Event
+
+```python
+audit_logger.info(
+    "Permission granted",
+    extra={
+        "event": "auth.permission.granted",
+        "actor_user_id": actor.id,
+        "target_user_id": target.id,
+        "permission": permission,
+        "tenant_id": tenant_id,
+    },
+)
+```

package/roles/software-developer/backend/README.md

@@ -0,0 +1,26 @@
+# Backend
+
+Use this packet for service-side application code: APIs, workers, domain
+services, persistence orchestration, integrations, and runtime behavior.
+
+## Scope
+
+- Request handlers, service layers, repositories, workers, and schedulers.
+- Business rules, validations, transactions, retries, and idempotency.
+- External service integrations and background processing.
+- Operational readiness for backend services.
+
+## Standards
+
+- Keep business rules in testable service/domain code, not only transport handlers.
+- Make side effects explicit and idempotent where retries are possible.
+- Use transactions for multi-step persistence changes that must commit together.
+- Propagate correlation IDs and structured errors.
+- Add tests around behavior, failure modes, and boundary contracts.
+
+## Related Files
+
+- `../api/` for transport contracts.
+- `../database/` and `../sql/` for persistence.
+- `../messaging/` for async flows.
+- `../logging/` and `../observability/` for runtime signals.

package/roles/software-developer/backend/checklists.md

@@ -0,0 +1,21 @@
+# Backend Checklists
+
+## Design
+
+- [ ] Identify transport boundary, domain boundary, persistence boundary, and side effects.
+- [ ] Define failure modes, retry behavior, idempotency keys, and transaction boundaries.
+- [ ] Confirm input validation and output contract ownership.
+- [ ] Decide which behavior belongs in handler, service, repository, or worker code.
+
+## Implementation
+
+- [ ] Keep handlers thin and delegate business behavior to testable units.
+- [ ] Use shared clients, repositories, serializers, and error types.
+- [ ] Add timeouts and cancellation support for external calls.
+- [ ] Emit safe logs, metrics, and traces for critical paths.
+
+## Verification
+
+- [ ] Add unit tests for business rules.
+- [ ] Add integration tests for persistence or external boundaries.
+- [ ] Test timeout, retry, duplicate request, and dependency failure paths.

package/roles/software-developer/backend/examples.md

@@ -0,0 +1,21 @@
+# Backend Examples
+
+## Service Boundary
+
+```python
+class OrderService:
+    def __init__(self, orders: OrderRepository, payments: PaymentClient):
+        self.orders = orders
+        self.payments = payments
+
+    async def capture_order(self, order_id: str, actor: Principal) -> Order:
+        order = await self.orders.get_for_update(order_id)
+        order.require_action("capture", actor)
+        await self.payments.capture(order.payment_id, idempotency_key=order.id)
+        order.mark_captured()
+        await self.orders.save(order)
+        return order
+```
+
+Keep orchestration visible and push low-level persistence and transport details
+behind dedicated collaborators.

package/roles/software-developer/cache/README.md

@@ -0,0 +1,25 @@
+# Cache
+
+Use this packet when adding, changing, or reviewing in-memory, distributed,
+browser, CDN, database, or application-level caching.
+
+## Scope
+
+- Cache keys, values, expiry, invalidation, and warming.
+- Read-through, write-through, write-behind, and aside-cache patterns.
+- CDN and HTTP cache headers.
+- Stampede prevention, consistency trade-offs, and fallback behavior.
+
+## Standards
+
+- Cache only data that has clear freshness and invalidation rules.
+- Include tenant, locale, auth scope, and version dimensions in keys when relevant.
+- Prefer bounded TTLs and explicit invalidation for mutable data.
+- Prevent stampedes with locks, single-flight, jitter, or stale-while-revalidate.
+- Never cache secrets or user-private data in shared scopes.
+
+## Related Files
+
+- `../performance/` for measurement.
+- `../backend/` for service integration.
+- `../frontend/performance/` for browser-facing cache concerns.

package/roles/software-developer/cache/checklists.md

@@ -0,0 +1,21 @@
+# Cache Checklists
+
+## Design
+
+- [ ] Define source of truth, freshness target, TTL, and invalidation triggers.
+- [ ] Include all required dimensions in the cache key.
+- [ ] Decide behavior for miss, stale value, backend failure, and partial invalidation.
+- [ ] Estimate cardinality, memory cost, and eviction impact.
+
+## Implementation
+
+- [ ] Use stable key builders rather than ad hoc string construction.
+- [ ] Add TTL jitter for high-volume keys.
+- [ ] Protect shared caches from private or tenant-specific leakage.
+- [ ] Record hit rate, miss rate, latency, and eviction metrics.
+
+## Verification
+
+- [ ] Test hit, miss, stale, invalidation, and backend failure paths.
+- [ ] Verify cross-user and cross-tenant data cannot leak.
+- [ ] Compare latency and load before and after caching.

package/roles/software-developer/cache/examples.md

@@ -0,0 +1,22 @@
+# Cache Examples
+
+## Key Builder
+
+```python
+def user_profile_cache_key(tenant_id: str, user_id: str, version: int) -> str:
+    return f"tenant:{tenant_id}:user:{user_id}:profile:v{version}"
+```
+
+## Cache Aside
+
+```python
+async def get_profile(tenant_id: str, user_id: str) -> Profile:
+    key = user_profile_cache_key(tenant_id, user_id, version=2)
+    cached = await cache.get(key)
+    if cached is not None:
+        return Profile.model_validate_json(cached)
+
+    profile = await repository.get_profile(tenant_id, user_id)
+    await cache.set(key, profile.model_dump_json(), ttl_seconds=300)
+    return profile
+```

package/roles/software-developer/checklists.md

@@ -0,0 +1,122 @@
+# Project‑Level Checklists for a Senior Software Developer
+
+A collection of reusable task lists that cover the complete lifecycle of a work item – from receiving a request to shipping a production‑ready change.  
+Each checklist is written in **GitHub‑flavored Markdown task‑list syntax** (`- [ ]` = pending, `- [x]` = done) so you can tick boxes directly in most editors or on GitHub.
+
+---  
+
+## 📥 1. Receive Task & Clarify Scope  
+
+- [ ] **Acknowledge receipt** (comment or message).  
+- [ ] Identify **problem statement**, **acceptance criteria**, and **success metrics**.  
+- [ ] Note any **deadlines**, **stakeholders**, and **dependencies**.  
+- [ ] Add a short **summary** to the task tracker (Jira, GitHub Issues, etc.).  
+
+---  
+
+## 🧭 2. Load Context  
+
+- [ ] Load `context/engineering.md` – overall team processes, conventions, and tooling.  
+- [ ] Load `projects/<project>/context.md` (or `context/<project>.md` if a different naming convention is used).  
+- [ ] Identify relevant **service boundaries**, **API contracts**, and **data stores** affected.  
+- [ ] Verify **access permissions** (repo, cloud resources, secrets manager).  
+- [ ] Check for any **existing design docs**, **architecture diagrams**, or **runbooks** related to the area.  
+
+---  
+
+## 📚 3. Load & Apply Relevant Skills  
+
+- [ ] Include / reference `skills/software-development/skill.md`.  
+- [ ] As needed, load:  
+  - `skills/security/`  
+  - `skills/performance/`  
+  - `skills/qa/`  
+  - `skills/software-development/skill.md` for API and database patterns  
+  - `roles/software-developer/api/` for endpoint-specific guidance  
+- [ ] Confirm that the proposed change does **not violate** any policy in those skill files (e.g., secret handling, performance thresholds, test coverage).  
+
+---  
+
+## 🏗️ 4. Design Solution  
+
+- [ ] Sketch a **high‑level diagram** (component, data flow, or API contract) if needed.  
+- [ ] List **design alternatives** and **rationale** for the chosen path.  
+- [ ] Identify **trade‑offs** (simplicity vs. performance, short‑term hack vs. long‑term refactor).  
+- [ ] Document **constraints** (e.g., latency target, security requirements, compliance).  
+- [ ] Add **TODO** markers for any open questions that will need resolution later.  
+
+---  
+
+## ✍️ 5. Implement  
+
+- [ ] Write **production‑ready code** that follows project conventions.  
+- [ ] Keep changes **focused** – single responsibility or feature flag where appropriate.  
+- [ ] Add **inline comments** for non‑obvious logic, not for stating the obvious.  
+- [ ] Ensure **no new third‑party dependencies** are introduced without approval.  
+- [ ] Re‑use existing **utilities**, **helper functions**, and **shared libraries**.  
+- [ ] Run **local static checks** (`ruff`, `mypy`, `pre‑commit`, etc.) and fix failures.  
+- [ ] Commit with a **clear, descriptive message** referencing the task ID if applicable.  
+
+---  
+
+## 🧪 6. Test  
+
+- [ ] Write **unit tests** for new/modified functions (aim for ≥ 80 % coverage of new code).  
+- [ ] Add **integration / contract tests** for any new or changed APIs.  
+- [ ] Run **property‑based tests** (if the project uses them).  
+- [ ] Execute **end‑to‑end tests** that exercise the full pipeline.  
+- [ ] Perform **performance sanity checks** – does latency/throughput meet the baseline?  
+- [ ] Verify **security scans** (`bandit`, `safety`, secret detection) pass.  
+- [ ] Confirm **all tests pass** on the CI pipeline locally before pushing.  
+
+---  
+
+## 📄 7. Review & Refactor  
+
+- [ ] Submit a **Pull Request / Merge Request** with:  
+  - Clear description of *what* was changed and *why*.  
+  - Links to relevant **design docs** or **issue tickets**.  
+  - Checklist of **testing results**.  
+- [ ] Address feedback from **code reviewers** (must be approved by at least one senior reviewer).  
+- [ ] Re‑run CI after incorporating review changes.  
+- [ ] Perform a **final refactor pass** to eliminate dead code or duplicated logic.  
+- [ ] Ensure **test suite still passes** after refactor.  
+
+---  
+
+## 📚 8. Update Documentation  
+
+- [ ] Update **README** / service documentation with any new configuration options or deployment steps.  
+- [ ] Regenerate / update **API spec** (OpenAPI, Protobuf, etc.) if an endpoint was added/changed.  
+- [ ] Add or amend **architecture diagrams** where relevant.  
+- [ ] Document **known limitations** or **operational runbooks** (e.g., scaling limits, rollback procedure).  
+- [ ] Link the updated docs in the PR description and in the task tracker.  
+
+---  
+
+## 🚀 9. Deploy / Release  
+
+- [ ] Increment version numbers in `pyproject.toml` / `requirements.txt` and push tags.  
+- [ ] Build **Docker** (or OCI) image, push to the registry, and update Helm/K8s manifests.  
+- [ ] Run **canary / blue‑green** deployment if required, and monitor health metrics.  
+- [ ] Verify **observability** (metrics, logs, tracing) are emitting correct data for the new version.  
+- [ ] Conduct **post‑deployment validation** (functional smoke test, latency checks).  
+- [ ] Tag the release in Git (`model-release/vX.Y.Z`) and close the task.  
+
+---  
+
+## ✅ 10. Verify Success Criteria  
+
+- [ ] Confirm the original **problem statement** has been resolved.  
+- [ ] Verify adherence to **project conventions** and **coding standards**.  
+- [ ] Ensure the change is **production‑ready** (builds, deploys, runs).  
+- [ ] Check that **appropriate tests** exist and pass.  
+- [ ] Validate that **technical debt** has not increased (no new TODOs left behind).  
+- [ ] Ensure significant decisions are **clearly explained** (in code comments, docs, or PR discussion).  
+
+---  
+
+### Completion
+
+When all checklist items are ticked, the work is considered **complete** and ready for merging.  
+Keep this file handy; you can copy it into new projects or create project‑specific variants (e.g., `checklists/frontend.md`, `checklists/mlops.md`) by selecting the relevant sections.

package/roles/software-developer/code-review/README.md

@@ -0,0 +1,23 @@
+# Code Review
+
+Use this packet when reviewing or preparing changes for review.
+
+## Scope
+
+- Pull requests, merge requests, design reviews, and AI-generated code review.
+- Correctness, security, maintainability, tests, performance, and operability.
+- Review comments, approval criteria, and follow-up tracking.
+
+## Standards
+
+- Lead with correctness, safety, and user impact.
+- Cite concrete files, lines, behavior, and reproduction steps.
+- Separate blocking issues from preferences.
+- Check tests and verification evidence.
+- Keep feedback direct, respectful, and specific.
+
+## Related Files
+
+- `../checklists.md` for delivery gates.
+- `../refactoring/` for safe change shaping.
+- `context/communication.md` for feedback style.

package/roles/software-developer/code-review/checklists.md

@@ -0,0 +1,22 @@
+# Code Review Checklists
+
+## Reviewer
+
+- [ ] Confirm the change matches the stated requirement.
+- [ ] Check edge cases, error handling, security, and privacy behavior.
+- [ ] Verify tests cover the changed behavior and likely regressions.
+- [ ] Look for unnecessary complexity, duplication, or new dependencies.
+- [ ] Confirm docs, migrations, observability, and rollout notes are updated when needed.
+
+## Author
+
+- [ ] Keep the diff focused and reviewable.
+- [ ] Explain what changed, why, and how it was verified.
+- [ ] Link issues, design notes, screenshots, logs, or test output where useful.
+- [ ] Resolve or explicitly track review comments.
+
+## Comment Quality
+
+- [ ] Mark severity when the issue is blocking.
+- [ ] Suggest a concrete fix or ask a precise question.
+- [ ] Avoid vague comments such as "clean this up" without direction.

package/roles/software-developer/code-review/examples.md

@@ -0,0 +1,20 @@
+# Code Review Examples
+
+## Blocking Finding
+
+```text
+[P1] Cross-tenant authorization bypass
+
+This handler loads the invoice by ID before checking tenant ownership. A user who
+can guess another tenant's invoice ID could read metadata. Load by tenant_id and
+invoice_id together, or check ownership before returning any fields.
+```
+
+## Non-Blocking Suggestion
+
+```text
+[P3] Consider extracting the retry delay calculation
+
+The retry policy is correct, but the inline arithmetic is hard to scan. A small
+helper would make the jitter and max-delay behavior easier to test.
+```

package/roles/software-developer/database/README.md

@@ -0,0 +1,27 @@
+# Database
+
+Use this packet for persistence design that is not specific to one database
+family. It covers data modeling, migrations, transactions, consistency, and
+operational safety.
+
+## Scope
+
+- Schema design, data access patterns, migrations, and backfills.
+- Transactions, isolation, constraints, indexes, and consistency trade-offs.
+- Backup, restore, retention, archival, and data deletion.
+- Database access from services, workers, and reporting flows.
+
+## Standards
+
+- Treat the database as a shared contract with operational consequences.
+- Prefer explicit constraints over relying only on application checks.
+- Make migrations reversible or provide a documented rollback path.
+- Separate online request paths from heavy analytical or backfill work.
+- Test migrations and data transformations against representative data.
+
+## Related Files
+
+- `../sql/` for relational database guidance.
+- `../nosql/` for document, key-value, and wide-column systems.
+- `../backend/` for repository/service integration.
+- `skills/security/` for data privacy and retention.

package/roles/software-developer/database/checklists.md

@@ -0,0 +1,21 @@
+# Database Checklists
+
+## Design
+
+- [ ] Define entities, relationships, ownership, retention, and privacy constraints.
+- [ ] Choose transaction boundaries and consistency expectations.
+- [ ] Identify indexes, uniqueness constraints, and query patterns.
+- [ ] Plan migrations, backfills, rollback, and deployment order.
+
+## Implementation
+
+- [ ] Use parameterized queries or approved ORM/query builders.
+- [ ] Add constraints for required invariants.
+- [ ] Keep long-running migrations out of request-critical deployment steps.
+- [ ] Add observability for slow queries, lock waits, and migration progress.
+
+## Verification
+
+- [ ] Test schema migration forward and rollback paths when supported.
+- [ ] Test duplicate, missing, invalid, and concurrent-write cases.
+- [ ] Inspect query plans for hot paths and newly added indexes.

package/roles/software-developer/database/examples.md

@@ -0,0 +1,27 @@
+# Database Examples
+
+## Migration Plan
+
+```text
+1. Add nullable column.
+2. Deploy application code that writes both old and new fields.
+3. Backfill existing rows in batches.
+4. Add constraint after backfill validation.
+5. Remove old field usage in a later deploy.
+```
+
+## Repository Boundary
+
+```python
+class UserRepository:
+    async def get_by_tenant_and_id(self, tenant_id: str, user_id: str) -> User | None:
+        row = await self.db.fetch_one(
+            """
+            select id, tenant_id, email, status
+            from users
+            where tenant_id = :tenant_id and id = :user_id
+            """,
+            {"tenant_id": tenant_id, "user_id": user_id},
+        )
+        return User.model_validate(row) if row else None
+```

package/roles/software-developer/debugging/README.md

@@ -0,0 +1,24 @@
+# Debugging
+
+Use this packet when investigating defects, regressions, incidents, flaky tests,
+performance anomalies, or unexpected behavior.
+
+## Scope
+
+- Reproduction, hypothesis building, instrumentation, isolation, and verification.
+- Local debugging, production diagnosis, logs, traces, metrics, and test failures.
+- Root cause analysis and regression prevention.
+
+## Standards
+
+- Reproduce before changing code whenever feasible.
+- Change one variable at a time while investigating.
+- Prefer evidence over guesses.
+- Keep diagnostic changes separate from the final fix where possible.
+- Add regression tests or monitors after fixing confirmed bugs.
+
+## Related Files
+
+- `../logging/` and `../observability/` for runtime evidence.
+- `../testing/` for regression coverage.
+- `../frontend/debugging/` for browser-specific debugging.

package/roles/software-developer/debugging/checklists.md

@@ -0,0 +1,20 @@
+# Debugging Checklists
+
+## Investigation
+
+- [ ] Capture exact symptoms, inputs, environment, version, and timestamps.
+- [ ] Reproduce locally or identify the closest observable production signal.
+- [ ] List hypotheses and rank by likelihood and blast radius.
+- [ ] Inspect logs, traces, metrics, diffs, and recent deploys.
+
+## Fix
+
+- [ ] Make the smallest change that addresses the confirmed cause.
+- [ ] Remove temporary diagnostics or lower them to appropriate structured logs.
+- [ ] Add tests for the failure mode.
+- [ ] Confirm adjacent behavior still works.
+
+## Closure
+
+- [ ] Document root cause when the issue was user-visible or operationally significant.
+- [ ] Add follow-up tasks for monitoring, tooling, or design gaps.

package/roles/software-developer/debugging/examples.md

@@ -0,0 +1,28 @@
+# Debugging Examples
+
+## Hypothesis Log
+
+```text
+Symptom: payment jobs retry forever after provider timeout.
+
+Evidence:
+- Retry count increases every 30 seconds.
+- Provider request times out at 10 seconds.
+- Job state remains "processing".
+
+Hypothesis:
+- Timeout path raises before job state is moved back to "queued".
+
+Verification:
+- Unit test timeout branch and inspect state transition.
+```
+
+## Regression Test Shape
+
+```python
+async def test_timeout_requeues_payment_job(payment_worker, timeout_payment_client):
+    job = await payment_worker.run_once()
+
+    assert job.status == "queued"
+    assert job.retry_count == 1
+```

package/roles/software-developer/examples/README.md

@@ -0,0 +1,22 @@
+# Role Examples
+
+This folder is reserved for larger end-to-end examples that are too specific for
+the top-level `examples.md` file.
+
+## Use Cases
+
+- Complete feature walkthroughs.
+- Multi-service change examples.
+- Review examples with before-and-after diffs.
+- Incident investigation narratives.
+
+## File Naming
+
+Use descriptive lowercase names:
+
+- `api-contract-change.md`
+- `background-job-retry.md`
+- `database-migration-rollout.md`
+- `frontend-form-validation.md`
+
+Keep examples tied to role behavior and link back to topic packets when useful.

package/roles/software-developer/examples/checklists.md

@@ -0,0 +1,8 @@
+# Example Authoring Checklist
+
+- [ ] State the scenario and why it matters.
+- [ ] Show the starting point or problem.
+- [ ] Show the implementation or review approach.
+- [ ] Include tests, verification, or operational signals.
+- [ ] Link to relevant topic folders such as `../api/`, `../database/`, or `../testing/`.
+- [ ] Avoid project secrets, private data, and organization-specific credentials.

package/roles/software-developer/examples/examples.md

@@ -0,0 +1,25 @@
+# Example Index
+
+Add larger examples here as the role grows.
+
+## Starter Example Template
+
+```markdown
+# Scenario Name
+
+## Problem
+
+What failed or what needs to be built.
+
+## Approach
+
+The design and implementation path.
+
+## Verification
+
+Tests, checks, logs, screenshots, or rollout evidence.
+
+## Follow-Ups
+
+Known gaps or later improvements.
+```