148 lines
18 KiB
Markdown
148 lines
18 KiB
Markdown
# 21 — Initial seed catalog
|
||
|
||
The product roadmap contains **72 distinct playbook concepts**. All **28 P0 entries are delivered as publishable package directories** under `content/playbooks/`. P1 and P2 entries remain explicitly labeled authored backlog. The machine-readable source is `catalog/seed-catalog.yaml`; runtime delivery rules are in `docs/36-seed-content-delivery.md`.
|
||
|
||
## Catalog design rules
|
||
|
||
- Every entry solves a distinct recurring development job.
|
||
- Audit and plan playbooks do not accidentally authorize code changes.
|
||
- High-risk work defaults to planning or evidence-heavy verification.
|
||
- Generic titles remain repository-aware through profiles and typed inputs.
|
||
- A catalog entry is not `Validated` until a full package and evaluation evidence exist.
|
||
|
||
## Priority summary
|
||
|
||
| Priority | Meaning | Count |
|
||
|---|---|---:|
|
||
| P0 | Publishable launch catalog | 28 |
|
||
| P1 | Early expansion | 36 |
|
||
| P2 | Specialized expansion | 8 |
|
||
|
||
## Repository Understanding
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Repository Inventory and Map** (`repository-inventory`) | guided | low | diagnose | Build an evidence-based inventory of applications, services, packages, data stores, deployment assets and key relationships without changing the repository. |
|
||
| P1 | **Reconstruct Current Architecture** (`architecture-reconstruction`) | run-pack | low | diagnose | Infer and document the current architecture, boundaries and data flows from code and configuration while distinguishing observation from inference. |
|
||
| P1 | **Trace a Critical User or Data Flow** (`critical-flow-tracing`) | guided | low | diagnose | Follow one critical flow across frontend, API, persistence and external integrations to expose behavior, dependencies and failure points. |
|
||
| P0 | **Generate Developer Onboarding Guide** (`onboarding-documentation`) | run-pack | low | plan | Create accurate setup, architecture and contribution guidance from repository evidence without inventing unavailable commands. |
|
||
| P0 | **Generate Repository AGENTS.md Guidance** (`agents-instructions`) | guided | moderate | plan | Create reviewed persistent Codex instructions from real repository commands, protected paths and engineering policies. |
|
||
| P1 | **Documentation-to-Code Drift Audit** (`documentation-code-drift`) | guided | low | diagnose | Compare setup, API, configuration and operational documentation with actual implementation and report stale or misleading content. |
|
||
| P2 | **Dependency Surface Map** (`dependency-surface-map`) | guided | low | diagnose | Map internal package dependencies and important external integrations to reveal coupling, cycles and critical dependency paths. |
|
||
| P1 | **Create Evidence-Based Technical Debt Register** (`technical-debt-register`) | run-pack | low | plan | Convert observable maintainability, reliability and operational issues into a prioritized register with impact, evidence and remediation shape. |
|
||
|
||
## Audits
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Repository Health Audit** (`repository-health-audit`) | guided | low | diagnose | Assess repository hygiene, documentation, testing, dependency management, release readiness and agent readiness without making changes. |
|
||
| P1 | **Architecture Quality Audit** (`architecture-audit`) | run-pack | moderate | diagnose | Review boundaries, coupling, data ownership, dependency direction and operational fit against the repository’s stated goals. |
|
||
| P0 | **Frontend UX and Interaction Audit** (`frontend-ux-audit`) | guided | low | diagnose | Evaluate hierarchy, interaction clarity, responsive behavior, empty states, consistency and perceived product quality using the running application where available. |
|
||
| P0 | **Accessibility Audit** (`accessibility-audit`) | guided | moderate | diagnose | Audit semantic structure, keyboard use, focus, forms, contrast, motion and assistive-technology behavior for selected user flows. |
|
||
| P1 | **Application Performance Audit** (`performance-audit`) | run-pack | moderate | diagnose | Identify measurable frontend, backend, database and build-performance bottlenecks before proposing targeted improvements. |
|
||
| P1 | **API Contract and Compatibility Audit** (`api-contract-audit`) | guided | moderate | diagnose | Assess API consistency, validation, errors, versioning, idempotency and backwards-compatibility risks. |
|
||
| P1 | **Database Design and Query Audit** (`database-audit`) | run-pack | high | diagnose | Review schema design, indexes, query patterns, transactions, migrations and data-integrity controls using available evidence. |
|
||
| P0 | **Docker and Self-Hosting Audit** (`docker-self-hosting-audit`) | guided | moderate | diagnose | Review container security, image size, health checks, persistence, configuration and operability for self-hosted deployment. |
|
||
| P1 | **Logging and Observability Audit** (`observability-audit`) | guided | moderate | diagnose | Assess whether logs, metrics, health checks and audit events support troubleshooting without leaking sensitive data. |
|
||
| P0 | **Production Readiness Audit** (`production-readiness-audit`) | run-pack | high | plan | Evaluate deployability, security, migrations, recovery, monitoring, documentation and release evidence before production use. |
|
||
|
||
## Bugfixing
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Root-Cause Bug Fix** (`root-cause-bugfix`) | guided | moderate | verify | Reproduce a reported defect, identify its root cause, add regression evidence and implement the smallest structural fix. |
|
||
| P1 | **Flaky Test Investigation and Repair** (`flaky-test-repair`) | guided | moderate | verify | Measure, isolate and fix nondeterministic tests without masking real product defects or adding arbitrary retries. |
|
||
| P0 | **Build Failure Recovery** (`build-failure-recovery`) | guided | moderate | verify | Diagnose and repair a failing build while preserving intended build checks and avoiding broad dependency churn. |
|
||
| P1 | **Dependency Conflict Repair** (`dependency-conflict-repair`) | guided | moderate | verify | Resolve incompatible or duplicated dependencies with a minimal, explainable dependency graph change and full install/build validation. |
|
||
| P1 | **Frontend State and Lifecycle Bug Fix** (`frontend-state-bug`) | guided | moderate | verify | Trace incorrect UI state across events, effects, cache and asynchronous boundaries before implementing a regression-tested repair. |
|
||
| P1 | **External API Integration Failure** (`api-integration-failure`) | guided | high | verify | Diagnose request, authentication, schema, retry and error-handling failures without exposing credentials or weakening security. |
|
||
| P2 | **Database Concurrency Bug Investigation** (`database-concurrency-bug`) | run-pack | high | verify | Reproduce and repair race conditions, duplicate work or transaction anomalies with data-integrity evidence and safe migration handling. |
|
||
| P1 | **Post-Upgrade Regression Repair** (`upgrade-regression-repair`) | guided | moderate | verify | Compare pre/post-upgrade behavior, isolate the compatibility break and repair it without reverting unrelated security or maintenance improvements. |
|
||
|
||
## Code Quality
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Repository Cleanup and Hygiene** (`repository-cleanup`) | guided | moderate | verify | Remove dead files, stale scripts, generated artifacts and unused dependencies while preserving behavior and repository history. |
|
||
| P1 | **Decompose an Oversized Module** (`large-module-decomposition`) | run-pack | moderate | verify | Split a large module along real responsibilities while preserving public behavior and avoiding speculative abstraction. |
|
||
| P1 | **Reduce Harmful Duplication** (`duplication-reduction`) | guided | moderate | verify | Identify duplicated logic with meaningful maintenance cost and consolidate it without creating an over-generalized abstraction. |
|
||
| P0 | **Harden Error Handling** (`error-handling-hardening`) | guided | moderate | verify | Improve error classification, propagation, user feedback and safe logging across a selected flow. |
|
||
| P1 | **Improve Type Safety** (`type-safety-improvement`) | guided | moderate | verify | Replace unsafe casts, implicit any-like behavior and unchecked external data with validated, maintainable types. |
|
||
| P1 | **Centralize Configuration Safely** (`configuration-centralization`) | guided | moderate | verify | Consolidate duplicated and hardcoded configuration with typed validation, clear defaults and environment separation. |
|
||
| P1 | **Improve Operational Logging** (`logging-improvement`) | guided | moderate | verify | Add structured, actionable and privacy-safe logs around critical operations without noisy duplication. |
|
||
| P2 | **Targeted Performance Refactor** (`performance-refactor`) | run-pack | high | verify | Implement a measured performance improvement for one confirmed bottleneck and prove the before/after result. |
|
||
|
||
## Testing
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Establish Unit Test Foundation** (`unit-test-foundation`) | run-pack | moderate | verify | Introduce a maintainable unit-test baseline around core domain behavior without over-mocking implementation details. |
|
||
| P1 | **Establish Integration Test Foundation** (`integration-test-foundation`) | run-pack | moderate | verify | Add real integration tests for persistence or service boundaries using isolated, reproducible dependencies. |
|
||
| P0 | **Add Playwright Critical-Flow Tests** (`playwright-critical-flows`) | run-pack | moderate | verify | Cover selected end-to-end user journeys with resilient selectors, deterministic setup and useful failure artifacts. |
|
||
| P1 | **Build a Focused Regression Suite** (`regression-suite`) | run-pack | moderate | verify | Turn historically costly defects and critical behaviors into a prioritized regression suite. |
|
||
| P1 | **Improve Test Isolation** (`test-isolation`) | guided | moderate | verify | Remove order dependence, shared state and environment leakage while preserving realistic integration behavior. |
|
||
| P2 | **Speed Up Test Execution** (`test-performance`) | guided | moderate | verify | Measure test-suite bottlenecks and improve execution time without reducing meaningful coverage or hiding slow failures. |
|
||
| P1 | **Add API or Integration Contract Tests** (`contract-tests`) | run-pack | moderate | verify | Protect external and internal service contracts with schema, compatibility and error-behavior tests. |
|
||
| P2 | **Refactor Test Fixtures and Builders** (`test-fixture-cleanup`) | guided | low | verify | Replace duplicated or opaque fixtures with clear builders and data ownership while preserving test intent. |
|
||
|
||
## Feature Implementation
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Implement a Feature from a Functional Specification** (`feature-from-spec`) | run-pack | moderate | repair | Translate a bounded specification into architecture-aware code, tests, documentation and verified user behavior. |
|
||
| P1 | **Implement a Production-Ready CRUD Module** (`crud-module`) | run-pack | moderate | repair | Add a complete create/read/update/delete workflow with validation, authorization, persistence, errors and tests. |
|
||
| P0 | **Add a Compatible API Endpoint** (`api-endpoint`) | guided | moderate | verify | Implement a new endpoint with validated input, authorization, stable errors, documentation and contract tests. |
|
||
| P1 | **Add a Reliable Background Job** (`background-job`) | run-pack | high | repair | Implement idempotent queued work with progress, retries, leases, failure visibility and operational controls. |
|
||
| P1 | **Add Safe Import and Export** (`import-export`) | run-pack | high | repair | Implement schema-validated portable import/export with integrity checks, size limits and path safety. |
|
||
| P0 | **Add Search and Faceted Filtering** (`search-filter`) | guided | moderate | verify | Implement useful query, filter, sorting, URL state and no-results behavior over an existing dataset. |
|
||
| P2 | **Implement Roles and Permissions** (`role-permissions`) | run-pack | high | repair | Add explicit authorization rules, server-side enforcement, admin UX and cross-tenant tests. |
|
||
| P1 | **Implement an External Service Connector** (`connector-integration`) | run-pack | high | repair | Add a capability-detected, secret-safe connector with health, degraded states and bounded data synchronization. |
|
||
|
||
## Git Gitea
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Gitea Repository Best-Practices Audit** (`gitea-best-practices`) | guided | moderate | diagnose | Review repository metadata, branch/tag protection, templates, Actions, release flow and permissions using available evidence. |
|
||
| P0 | **Design Branch Protection Rules** (`branch-protection-plan`) | guided | moderate | plan | Produce a repository-appropriate branch protection plan covering pushes, merges, reviews, status checks and exceptions. |
|
||
| P1 | **Create Issue Template System** (`issue-template-system`) | guided | low | verify | Design and implement useful bug, feature and operational issue templates with labels and triage guidance. |
|
||
| P0 | **Create Pull Request Template and Review Checklist** (`pull-request-template`) | quick | low | verify | Add a concise pull-request template aligned with repository validation, risk and documentation needs. |
|
||
| P1 | **Design Gitea Release Process** (`release-process`) | run-pack | moderate | plan | Create a repeatable versioning, tagging, changelog, artifact and rollback workflow suitable for the repository. |
|
||
| P1 | **Gitea Actions Workflow Audit** (`actions-workflow-audit`) | guided | high | diagnose | Review workflows, triggers, permissions, secrets, caching and release behavior for correctness and security. |
|
||
| P0 | **Audit and Repair .gitignore Hygiene** (`gitignore-hygiene`) | guided | moderate | verify | Identify tracked runtime/generated files and improve ignore rules without hiding required source or configuration examples. |
|
||
| P2 | **Improve Repository Metadata and Discoverability** (`repository-metadata`) | guided | low | verify | Align description, topics, README, license, contribution and release metadata for clear internal or public use. |
|
||
|
||
## Release Operations
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Prepare a Release Candidate** (`release-candidate-prep`) | run-pack | high | repair | Execute a bounded release-readiness pass covering versions, migrations, tests, artifacts, documentation and known limitations. |
|
||
| P0 | **Clean-Room Installation Validation** (`clean-room-validation`) | run-pack | moderate | verify | Prove that a fresh clone or deployment can be installed, configured and exercised using only documented steps. |
|
||
| P1 | **Database Migration Readiness** (`migration-readiness`) | run-pack | critical | plan | Review and validate pending migrations, compatibility, backup, rollback and deployment sequencing. |
|
||
| P0 | **Backup and Restore Validation** (`backup-restore-validation`) | run-pack | high | verify | Test that application data, artifacts, configuration and encryption-key dependencies can be backed up and restored. |
|
||
| P1 | **Harden and Optimize Docker Images** (`docker-image-hardening`) | guided | high | verify | Reduce image risk and size while preserving runtime behavior, non-root operation and health checks. |
|
||
| P0 | **Implement Health and Readiness Checks** (`health-readiness`) | guided | moderate | verify | Add accurate liveness, readiness and dependency health without hiding partial outages. |
|
||
| P1 | **Create Release Rollback Plan** (`rollback-plan`) | guided | high | plan | Document and validate rollback boundaries for application, configuration, database and artifacts. |
|
||
| P0 | **Generate Evidence-Based Release Notes** (`release-notes`) | quick | low | plan | Create concise release notes from verified changes, migrations, fixes, known limitations and operator actions. |
|
||
|
||
## Security Reliability
|
||
|
||
| Priority | Playbook | Type | Risk | Default | Outcome |
|
||
|---|---|---|---|---|---|
|
||
| P0 | **Security Hygiene Audit** (`security-hygiene-audit`) | run-pack | high | diagnose | Review authentication, authorization, secrets, input validation, dependency risk and unsafe defaults within a defined application scope. |
|
||
| P0 | **Secrets Exposure Audit** (`secrets-exposure-audit`) | guided | critical | diagnose | Inspect repository and runtime configuration patterns for committed, logged or exported secrets without echoing sensitive values. |
|
||
| P1 | **Authorization Boundary Review** (`authorization-review`) | run-pack | high | diagnose | Trace protected resources and operations to verify server-side enforcement and cross-user or cross-workspace isolation. |
|
||
| P1 | **Create Application Threat Model** (`threat-model`) | run-pack | moderate | plan | Identify assets, trust boundaries, abuse cases and prioritized controls tied to the actual architecture. |
|
||
| P1 | **Failure and Resilience Review** (`resilience-failure-review`) | run-pack | high | diagnose | Assess dependency outages, retry behavior, idempotency, data loss, degraded states and recovery visibility. |
|
||
| P2 | **Privacy and Data Handling Review** (`privacy-data-review`) | run-pack | high | diagnose | Map personal or sensitive data, retention, exports, logging and deletion behavior to identify unnecessary collection and leakage risks. |
|
||
|
||
## Fully authored example packages
|
||
|
||
- `repository-health-audit`
|
||
- `root-cause-bugfix`
|
||
- `repository-cleanup`
|
||
- `gitea-best-practices`
|
||
- `feature-from-spec`
|
||
- `production-readiness-audit`
|
||
|
||
These six packages are duplicated under `examples/playbooks/` as normative patterns. They are also part of the 28-package P0 runtime catalog. The other 22 P0 packages are complete publishable packages; P1 and P2 remain governed backlog and must not appear as executable content until promoted through document 36.
|