opencode-codeops 1.4.0

package/skills/retro-requirements/phases.md

@@ -0,0 +1,609 @@
+# Phases 0–9: Detailed Instructions & Output Templates
+
+Read the relevant section before executing each phase. All output is written to
+**the resolved `_retro/` dir** — the layout-aware path defined ONCE in SKILL.md's
+resolution block (never re-derive it here). Confidence classification (Phases 4+) is detailed in
+`confidence-classification.md`; the Phase 8B gate is in `triage-gate.md`.
+
+In every template below, replace `[Date]` with the current date and `[Name]`
+with the project name. Each output file opens with a short banner naming the
+phase that generated it.
+
+---
+
+## Phase 0: Reconnaissance
+
+**Goal:** Establish what the project IS before reading any source code.
+
+### 0.1 Manifest Analysis
+
+Read all manifest/config files at the project root and extract:
+
+| File | Extract |
+|------|---------|
+| `package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` / `*.csproj` / `build.gradle` | Name, version, dependencies, scripts, language |
+| `docker-compose.yml` / `Dockerfile` | Services, infrastructure, deployment model |
+| `tsconfig.json` / `webpack.config.*` / `vite.config.*` / `.babelrc` | Build toolchain |
+| `.env.example` / `.env.template` | Environment variables (configuration surface) |
+| `README.md` / `CHANGELOG.md` | Project description, history, documentation |
+| the project's AGENTS.md (or detected project conventions) | Existing project configuration (if available) |
+| `Makefile` / `justfile` / `Taskfile.yml` | Build/task commands |
+| `.github/workflows/*` / `.gitlab-ci.yml` | CI/CD pipeline |
+
+### 0.2 Directory Structure Mapping
+
+List the project tree (top-level first, then selective recursion):
+
+- Identify each top-level directory's purpose
+- Count files and estimate lines of code per module
+- Classify the project type (web app, API, library, CLI, mobile, etc.)
+- Detect monorepo structure (multiple packages/services)
+
+### 0.3 Output: `00-project-profile.md`
+
+```markdown
+# Project Profile: [Name]
+
+> Generated by retro-requirements — Phase 0: Reconnaissance
+> Date: [Date] · Source: [Project root path]
+
+## Identity
+- **Name:** [Project name]
+- **Type:** [web-app / api / library / cli / mobile / monorepo / etc.]
+- **Description:** [From README or inferred from code]
+- **Version:** [Current version]
+
+## Technology Stack
+| Layer | Technology | Evidence |
+|-------|-----------|----------|
+| Language(s) | [e.g., TypeScript] | [e.g., tsconfig.json, .ts files] |
+| Framework(s) | [e.g., Express, React] | [package.json dependency] |
+| Database(s) | [e.g., PostgreSQL] | [docker-compose, migrations] |
+| Build Tool | [e.g., tsc, webpack] | [build script] |
+| Test Framework | [e.g., Vitest, Jest] | [test script, config file] |
+| Package Manager | [e.g., yarn, npm, cargo] | [lockfile present] |
+
+## Scale Estimate
+- **Total Files / Estimated LOC / Modules / Dependencies:** [counts]
+
+## Directory Structure
+[Annotated tree with the purpose of each top-level directory]
+
+## Key Configuration
+### Environment Variables
+[Extracted from .env.example or config files]
+### Scripts/Commands
+[Extracted from package.json scripts, Makefile, etc.]
+
+## Existing Documentation
+[List of docs found: README, CHANGELOG, wiki, docs/, etc.]
+```
+
+---
+
+## Phase 1: Structural Analysis
+
+**Goal:** Understand the architecture — how the code is organized into layers,
+modules, and components.
+
+### 1.1 Entry Point Identification
+Find and read all entry points: main app entry (`src/index.ts`, `main.go`,
+`app.py`), route/endpoint registrations, CLI command registrations, event/message
+handlers, scheduled tasks / cron jobs.
+
+### 1.2 Layer Identification
+Map architectural layers by reading directory structures and key files:
+
+| Pattern to Look For | Indicates |
+|---------------------|-----------|
+| `routes/`, `controllers/`, `handlers/` | API/HTTP layer |
+| `services/`, `domain/`, `core/` | Business logic layer |
+| `models/`, `entities/`, `schemas/` | Data model layer |
+| `repositories/`, `dal/`, `db/` | Data access layer |
+| `middleware/`, `interceptors/` | Cross-cutting middleware |
+| `utils/`, `helpers/`, `lib/` | Shared utilities |
+| `config/`, `settings/` | Configuration management |
+| `tests/`, `__tests__/`, `spec/` | Test organization |
+| `types/`, `interfaces/`, `contracts/` | Type definitions |
+| `views/`, `pages/`, `components/` | UI layer (if applicable) |
+| `migrations/`, `seeds/` | Database lifecycle |
+| `plugins/`, `extensions/`, `modules/` | Plugin architecture |
+
+### 1.3 Module Dependency Mapping
+For each module/layer, trace what it imports, what imports it, and the dependency
+direction (should be unidirectional: controllers → services → repositories).
+
+### 1.4 Pattern Recognition
+Identify recurring patterns and the evidence for each: MVC/MV*, layered
+architecture, DDD (bounded contexts, aggregates, value objects), event-driven,
+plugin architecture, microservices, monolith, CQRS, repository pattern.
+
+### 1.5 Output: `01-architecture-analysis.md`
+
+```markdown
+# Architecture Analysis: [Name]
+
+> Generated by retro-requirements — Phase 1: Structural Analysis · Date: [Date]
+
+## Architecture Style
+[e.g., "Layered monolith with MVC" or "Event-driven microservices"]
+
+## Layer Map
+| Layer | Directory | Purpose | Key Files |
+|-------|-----------|---------|-----------|
+
+## Entry Points
+| Entry Point | File | Purpose |
+|-------------|------|---------|
+
+## Module Dependency Graph
+[Text-based dependency diagram]
+
+## Patterns Identified
+| Pattern | Where | Evidence |
+|---------|-------|----------|
+
+## Architecture Decisions (Inferred)
+| Decision | Observed Choice | Likely Rationale |
+|----------|----------------|------------------|
+```
+
+---
+
+## Phase 2: Data Model Extraction
+
+**Goal:** Reconstruct the complete domain model — entities, relationships,
+constraints, and lifecycle.
+
+### 2.1 Entity Discovery
+Find data models in: ORM definitions (Sequelize, TypeORM, Prisma, SQLAlchemy,
+ActiveRecord, GORM, …); migration files; schema definitions (GraphQL, JSON
+Schema, Protobuf); domain classes/interfaces; seed/fixture files.
+
+### 2.2 For Each Entity, Extract
+- **Fields/Properties:** name, type, constraints (required, unique, default, max length)
+- **Relationships:** foreign keys, join tables, embedded documents
+- **Lifecycle:** creation, modification, soft-delete, archive, state transitions
+- **Validation:** server-side validation rules, custom validators
+- **Indexes:** performance-critical queries (inferred)
+- **Enums/Constants:** finite value sets (status codes, roles, types)
+
+### 2.3 Output: `02-domain-model.md`
+
+```markdown
+# Domain Model: [Name]
+
+> Generated by retro-requirements — Phase 2: Data Model Extraction · Date: [Date]
+
+## Entity Inventory
+| # | Entity | Description | Fields | Relationships |
+|---|--------|-------------|--------|---------------|
+
+## Entity Details
+### [Entity Name]
+**Description:** [What this entity represents in the domain]
+**Fields:**
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+**Relationships:** Has many / Belongs to … (via [field])
+**Lifecycle:** Created when … · Modified when … · Deleted [soft/hard] when …
+**Validation Rules:** [Rule 1, Rule 2, …]
+
+## Entity Relationship Map
+[Text-based ERD showing all relationships]
+
+## Enums & Constants
+| Name | Values | Used By |
+|------|--------|---------|
+
+## Data Invariants
+[Business rules about data integrity extracted from validation code]
+```
+
+---
+
+## Phase 3: API & Interface Surface
+
+**Goal:** Catalog every way the outside world interacts with the system.
+
+- **3.1 HTTP/REST endpoints:** method + path, request/query/path params, response
+  format & status codes, auth/authorization requirements, rate limiting.
+- **3.2 CLI commands:** name and subcommands, arguments and flags, output format, exit codes.
+- **3.3 Public library API:** signature with types, purpose/behavior, error conditions.
+- **3.4 Event interfaces:** published events (trigger, payload), consumed events
+  (handler, side effects), WebSocket channels/topics.
+
+### 3.5 Output: `03-api-surface.md`
+
+```markdown
+# API & Interface Surface: [Name]
+
+> Generated by retro-requirements — Phase 3: API & Interface Surface · Date: [Date]
+
+## HTTP Endpoints
+| Method | Path | Auth | Description | Request | Response |
+|--------|------|------|-------------|---------|----------|
+
+## Endpoint Details
+### [GROUP: Resource Name]
+#### [METHOD] [Path]
+**Purpose / Authentication / Authorization / Request / Response**
+**Business Rules:** [Rules extracted from the handler code]
+
+## CLI Commands (if applicable)
+| Command | Description | Arguments |
+|---------|-------------|-----------|
+
+## Events (if applicable)
+| Event | Trigger | Payload | Consumers |
+|-------|---------|---------|-----------|
+
+## Public API (if library)
+| Export | Type | Description |
+|--------|------|-------------|
+```
+
+---
+
+## Phase 4: Behavior Catalog — Feature Extraction
+
+**Goal:** Translate code-level implementation into requirement-level feature
+descriptions. This is the most important and most difficult phase.
+
+### 4.1 Approach
+For each module/service from Phase 1: read the implementation; extract WHAT it
+does (not HOW); write it as a requirement statement; identify edge cases handled
+in the code (error branches, validation failures); note multi-step workflows.
+
+### 4.2 Feature Statement Format
+```
+[CATEGORY]-[NUMBER]: [Actor] can [action] [conditions/constraints]
+  - Triggers:   [What initiates this]
+  - Result:     [What changes in the system]
+  - Edge cases: [What the code handles]
+  - Related:    [Other features this connects to]
+  - Confidence: [✅ Confirmed | ⚠️ Inferred | 🔴 Suspicious]
+```
+
+**Every feature MUST carry a confidence level** — see
+`confidence-classification.md`. This is the safeguard against the code-as-truth
+tautology and the source of the Phase 8B triage items.
+
+### 4.3 Feature Categories
+Organize by domain area, not by code module: User Management; Core Domain (the
+main business functionality); Data Management (CRUD, import/export, bulk);
+Workflow (multi-step, approvals, state machines); Notifications; Administration;
+Reporting.
+
+### 4.4 Output: `04-behavior-catalog.md`
+
+```markdown
+# Behavior Catalog: [Name]
+
+> Generated by retro-requirements — Phase 4: Feature Extraction · Date: [Date]
+
+## Feature Summary
+| # | Category | Features | Complexity |
+|---|----------|----------|------------|
+
+## [Category]: [Name]
+### [CAT]-01: [Feature Title]
+**Statement:** [Actor] can [action] [conditions]
+**Triggers / Result**
+**Edge Cases:** [extracted from error-handling code]
+**Evidence:** [source file(s) where this behavior lives]
+**Confidence:** [✅ / ⚠️ / 🔴 — with one-line justification]
+
+## Workflows (Multi-Step Processes)
+### Workflow: [Name]
+**Steps:** 1. … → triggers 2. … → if [condition] then [3a] else [3b]
+**Actors Involved / State Transitions**
+```
+
+---
+
+## Phase 5: Business Rules & Validation Logic
+
+**Goal:** Extract the domain rules encoded in the code but often undocumented.
+
+### 5.1 Where to Find Business Rules
+| Location | Type of Rule |
+|----------|-------------|
+| Validation middleware/decorators | Input constraints (format, range, required) |
+| Service-layer if/else branches | Domain logic (eligibility, permissions, limits) |
+| Database constraints | Data integrity (unique, foreign key, check) |
+| Authorization checks | Access control (who can do what) |
+| State-machine transitions | Lifecycle rules (valid transitions) |
+| Scheduled jobs / cron | Time-based rules (expiry, cleanup, reminders) |
+| Configuration / feature flags | Conditional behavior |
+
+### 5.2 Rule Classification
+For each rule capture: **Rule ID** `BR-[category]-[number]`; **Statement** (plain
+English, "A user cannot X unless Y"); **Type** (Validation / Authorization /
+Domain / Lifecycle / Temporal); **Enforcement** (where in code); **Consequence**
+(what happens on violation); and a **Confidence** level (✅/⚠️/🔴).
+
+### 5.3 Output: `05-business-rules.md`
+
+```markdown
+# Business Rules: [Name]
+
+> Generated by retro-requirements — Phase 5: Business Rules Extraction · Date: [Date]
+
+## Rule Summary
+| Type | Count | Examples |
+|------|-------|----------|
+| Validation / Authorization / Domain / Lifecycle / Temporal | … | … |
+
+## Validation Rules
+### BR-VAL-01: [Title]
+**Statement / Enforcement / Violation Response / Confidence**
+
+## Authorization Rules
+### BR-AUTH-01: [Title]
+**Statement / Enforcement / Roles Involved / Confidence**
+
+## Domain Logic Rules
+### BR-DOM-01: [Title]
+**Statement / Enforcement / Edge Cases / Confidence**
+
+## Lifecycle Rules
+### BR-LIFE-01: [Title]
+**Statement / Valid Transitions / Invalid Transitions / Confidence**
+
+## Temporal Rules
+### BR-TIME-01: [Title]
+**Statement / Schedule / Effect / Confidence**
+```
+
+---
+
+## Phase 6: Cross-Cutting Concerns
+
+**Goal:** Document system-wide patterns that span all modules.
+
+Analyze: **Authentication** (login flow, tokens, sessions, OAuth/OIDC);
+**Authorization** (RBAC/ABAC, permission checks, role hierarchies); **Error
+Handling** (global handler, codes, response format); **Logging** (logger, levels,
+structured logging, audit trail); **Caching** (strategy, invalidation, TTLs);
+**Configuration** (loading, env-specific settings, feature flags); **Validation**
+(framework, sanitization, schema); **i18n**; **Security** (CORS, CSP, rate
+limiting, sanitization, encryption); **Observability** (metrics, tracing, health
+checks). Also capture the **observed testing strategy** (framework, structure,
+coverage areas, patterns) — reference your project's coding/testing standards
+(AGENTS.md) when judging quality.
+
+### 6.2 Output: `06-cross-cutting.md`
+
+```markdown
+# Cross-Cutting Concerns: [Name]
+
+> Generated by retro-requirements — Phase 6: Cross-Cutting Concerns · Date: [Date]
+
+## Authentication — Strategy + Implementation (login, tokens, expiry)
+## Authorization — Model (RBAC/ABAC/Custom), Roles, Enforcement
+## Error Handling — Strategy + error response format
+## Logging & Audit — Framework + what is logged
+## Caching — Strategy, TTLs, invalidation, technology
+## Configuration Management — Sources + environment handling
+## Security Measures — CORS, rate limiting, sanitization, encryption
+## Testing Strategy (Observed) — Framework, structure, coverage, patterns
+```
+
+---
+
+## Phase 7: Integrations & External Dependencies
+
+**Goal:** Map every external system the code communicates with.
+
+Look for: HTTP client calls (`fetch`, `axios`, `reqwest`, `http.Client`);
+database connections/queries; message-queue producers/consumers (RabbitMQ, Kafka,
+SQS); email (SMTP, SendGrid, SES); file storage (S3, GCS, local FS); payment
+providers (Stripe, PayPal); auth providers (Auth0, Keycloak, Google OAuth);
+monitoring/analytics; third-party APIs.
+
+### 7.2 Output: `07-integrations.md`
+
+```markdown
+# Integrations: [Name]
+
+> Generated by retro-requirements — Phase 7: Integrations · Date: [Date]
+
+## Integration Map
+| # | System | Protocol | Direction | Purpose | Config |
+|---|--------|----------|-----------|---------|--------|
+
+## Integration Details
+### [System Name]
+**Type / Protocol / Purpose / Configuration (env vars, connection strings)**
+**Error Handling:** [retry, circuit breaker, fallback]
+**Data Flow:** Outbound [what is sent] · Inbound [what is received]
+```
+
+---
+
+## Phase 8: Gaps, Debt & Observations
+
+**Goal:** Document what's missing, broken, or incomplete — critical for honest
+requirements.
+
+### 8.1 What to Look For
+| Signal | Indicates |
+|--------|-----------|
+| `TODO`, `FIXME`, `HACK`, `XXX` comments | Known incomplete work |
+| Empty catch blocks | Missing error handling |
+| Commented-out code | Abandoned features or workarounds |
+| Missing tests for modules | Untested functionality |
+| Hardcoded values | Missing configuration |
+| Debug print/log statements | Debugging artifacts |
+| Disabled lint rules | Code-quality workarounds |
+| Unused imports / dead code | Refactoring debt |
+| Missing input validation | Security gaps |
+| No retry/circuit-breaker on external calls | Reliability gaps |
+
+### 8.2 Output: `08-gaps-and-debt.md`
+
+```markdown
+# Gaps & Technical Debt: [Name]
+
+> Generated by retro-requirements — Phase 8: Gaps & Debt · Date: [Date]
+
+## Summary
+| Category | Count | Severity |
+|----------|-------|----------|
+| Missing Features / Technical Debt / Security Gaps / Test Coverage Gaps | … | … |
+
+## Missing Features (Should Exist But Don't)
+| # | Gap | Expected Behavior | Impact |
+
+## Technical Debt
+| # | Issue | Location | Recommended Fix |
+
+## Security Gaps
+| # | Gap | Risk | Recommendation |
+
+## Test Coverage Gaps
+| # | Module/Feature | Current Coverage | Needed |
+
+## TODO/FIXME Inventory
+| # | Comment | File | Line | Context |
+
+## Known Bugs
+[Populated by Phase 8B: items the user decided are bugs (option A) land here.]
+```
+
+---
+
+## Phase 8B: Bug-or-Feature Triage Gate
+
+**🚨 HARD, NON-NEGOTIABLE GATE — must pass before Phase 9.** The full protocol,
+register format, gate rules, persistence, and a worked example are in
+**`triage-gate.md`**. Do not start Phase 9 until the register reads
+`✅ GATE PASSED`.
+
+---
+
+## Phase 9: Synthesis — The Reconstruction Brief
+
+**Goal:** Combine all phase outputs into a single document the make-requirements
+skill can consume.
+
+**🚨 PREREQUISITE:** Phase 8B MUST have passed. If the triage register has any
+unresolved items, STOP and complete Phase 8B first.
+
+### 9.1 Process
+1. Verify the triage register shows `✅ GATE PASSED`.
+2. Review all phase outputs (`00`–`08`).
+3. Translate code-level observations into requirement-level statements.
+4. Organize by domain area (not by code structure).
+5. Apply triage decisions — (A) Bug items are EXCLUDED; (C) Unsure items are
+   included with ⚠️ flags and listed under Open Questions.
+6. Write the brief in the make-requirements input format.
+7. Include confidence levels — the Feature Catalog and Business Rules tables MUST
+   carry the Confidence column from the Phase 4/5 annotations.
+
+### 9.2 Output: `09-reconstruction-brief.md`
+
+```markdown
+# Reconstruction Brief: [Name]
+
+> Generated by retro-requirements — Phase 9: Synthesis
+> Date: [Date] · Source Codebase: [Path]
+>
+> Usage: feed this document to the make-requirements skill as analysis-notes
+> input — "I have analysis notes in <resolved _retro dir>/09-reconstruction-brief.md".
+
+## Project Identity
+**Name / Type / Description** (as if pitching it to someone who's never seen it)
+**Problem Statement** (inferred from behavior) · **Target Users** (from auth/roles/UI)
+
+## Technology Decisions (Confirmed from Codebase)
+| Decision | Choice | Confidence |
+|----------|--------|------------|
+
+## Stakeholders / User Types
+| # | Role | Description | Key Capabilities |
+
+## Domain Model
+### Core Entities
+| Entity | Description | Key Fields | Relationships |
+### Entity Relationships
+[Text-based ERD or descriptions]
+
+## Feature Catalog
+### [Domain Area]: [Name]
+| # | Feature | Description | Complexity | Confidence |
+|---|---------|-------------|------------|------------|
+
+## Business Rules
+| # | Rule | Type | Description | Confidence |
+|---|------|------|-------------|------------|
+
+## Workflows
+### [Workflow Name] — Actors + numbered Steps → Outcomes
+
+## Integration Points
+| # | System | Purpose | Protocol |
+
+## Cross-Cutting Requirements
+| Concern | Current Implementation | Requirement Level |
+| Auth / Authz / Error Handling / Logging / Caching / Security | … | … |
+
+## Non-Functional Characteristics
+| Characteristic | Observed | Requirement |
+| Performance / Scalability / Reliability / Accessibility | … | … |
+
+## Known Gaps & Improvement Opportunities
+| # | Gap | Description | Recommendation |
+
+## Open Questions for Discovery
+Questions the code alone can't answer — explored during make-requirements:
+1. [e.g., "Is feature X intentional or a bug?" — every (C) Unsure triage item lands here]
+2. [e.g., "What is the expected behavior when Y?"]
+3. [e.g., "Are there planned features not yet implemented? What are the performance targets?"]
+```
+
+After completion, the next step is to feed the brief to the make-requirements
+skill: *"I have analysis notes in
+<resolved _retro dir>/09-reconstruction-brief.md"*.
+
+---
+
+## Progress Tracking: `_progress.md`
+
+```markdown
+# Retro Requirements Progress
+
+> Project: [Name] · Started: [Date] · Last Updated: [Date]
+
+## Phase Status
+| Phase | Status | Files Analyzed | Notes |
+|-------|--------|---------------|-------|
+| 0: Reconnaissance | ✅ Complete | [N] | — |
+| 1: Structural Analysis | ✅ Complete | [N] | — |
+| 2: Domain Model | 🔄 In Progress | [N/M] | Completed: … Remaining: … |
+| 3–9 | ⬜ Not Started | — | — |
+
+## Module Coverage
+| Module | Phase 2 | Phase 4 | Phase 5 | Notes |
+|--------|---------|---------|---------|-------|
+```
+
+Commit the `_retro/` files after each completed phase to prevent data loss across
+sessions, e.g. `docs(retro): complete Phase X — [phase name]`.
+
+---
+
+## Adapting to Project Type (full mapping)
+
+| Project Type | Phase Focus | Extra Attention |
+|---|---|---|
+| Web App (full-stack) | All phases equally | UI components, routing, state management, SSR |
+| API / Backend | Phases 2–5 heavy | Endpoint contracts, auth, data validation |
+| Library / SDK | Phase 3 heavy | Public API surface, backward compatibility, docs |
+| CLI Tool | Phase 3 heavy | Command structure, output format, exit codes, config |
+| Mobile App | Phase 4 heavy | Navigation, offline support, push notifications |
+| Microservices | Phase 7 heavy | Service boundaries, inter-service comms, data ownership |
+| Monorepo | Run per-package | Shared packages, cross-package dependencies |
+| Data Pipeline | Phases 5, 7 heavy | Data flow, transformation rules, scheduling |
+| Infrastructure | Phases 0, 7 heavy | Service definitions, networking, secrets management |