diff --git a/.cursor/README.md b/.cursor/README.md index e373682..205a40f 100644 --- a/.cursor/README.md +++ b/.cursor/README.md @@ -1,215 +1,96 @@ ## Developer TODO (Project Mode) -### BUILD (green-field or new features) +### BUILD ``` -1. Create _docs/00_problem/ — describe what you're building, restrictions, acceptance criteria and samples of data system works with +1. Create _docs/00_problem/ — describe what you're building - problem.md (required) - restrictions.md (required) - acceptance_criteria.md (required) - - input_data (required) + - input_data/ (required) - security_approach.md (optional) -2. /research — produces solution drafts in _docs/01_solution/ +2. /research — solution drafts → _docs/01_solution/ Run multiple times: Mode A → draft, Mode B → assess & revise - Finalize as solution.md -3. /plan — architecture, components, risks, tests, Jira epics → _docs/02_plans/ +3. /plan — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/ -4. /decompose — flat numbered task specs + _dependencies_table.md → _docs/02_tasks/ +4. /decompose — atomic task specs + dependency table → _docs/02_tasks/ -5. /implement — auto-orchestrates all tasks: batches by dependencies, launches parallel implementers, runs code review, loops until done - -6. commit & push +5. /implement — batched parallel agents, code review, commit per batch → _docs/03_implementation/ ``` -### SHIP (deploy and operate) +### SHIP ``` -7. /deploy — containerization, CI/CD, environment strategy, observability, deployment procedures (skill, 5-step workflow) +6. /deploy — containerization, CI/CD, environments, observability, procedures → _docs/02_plans/deployment/ ``` -### EVOLVE (maintenance and improvement) +### EVOLVE ``` -8. /refactor — structured refactoring (skill, 6-phase workflow) -9. /retrospective — collect metrics, analyze trends, produce improvement report (skill) +7. /refactor — structured refactoring → _docs/04_refactoring/ +8. /retrospective — metrics, trends, improvement actions → _docs/05_metrics/ ``` -## Implementation Flow - -### `/implement` - -Reads flat task files and `_dependencies_table.md` from `_docs/02_tasks/`. - -1. Parses dependency graph, detects which tasks are already completed -2. Computes next batch of tasks (max 4 parallel, respecting dependencies) -3. Assigns file ownership per agent to prevent conflicts -4. Launches `implementer` subagents in parallel immediately -5. Runs `/code-review` skill on the batch's changes -6. If review FAIL — blocks for user confirmation; otherwise continues -7. Runs tests, commits and pushes to remote -8. Loops until all tasks are done - -### `/code-review` - -Multi-phase code review invoked after each implementation batch: - -1. Context loading — reads task specs to understand intent -2. Spec compliance — verifies each acceptance criterion is satisfied -3. Code quality — SOLID, DRY, KISS, error handling, naming, complexity -4. Security quick-scan — injection, secrets, input validation -5. Performance scan — O(n^2), N+1, unbounded fetches -6. Cross-task consistency — interface compatibility across batch - -Produces structured findings with severity (Critical/High/Medium/Low) and verdict (PASS/FAIL/PASS_WITH_WARNINGS). - -### `/deploy` - -Comprehensive deployment skill (5-step workflow): - -1. Containerization — Dockerfiles per component, docker-compose for dev and tests -2. CI/CD Pipeline — lint, test, security scan, build, deploy with quality gates -3. Environment Strategy — dev, staging, production with secrets management -4. Observability — structured logging, metrics, tracing, alerting, dashboards -5. Deployment Procedures — rollback, health checks, graceful shutdown - -Outputs to `_docs/02_plans/deployment/`. Run after `/implement` or before first production release. - -### `/retrospective` - -Collects metrics from batch reports and code review findings, analyzes trends across implementation cycles, and produces improvement reports. Outputs to `_docs/05_metrics/`. - -### `/rollback` - -Reverts implementation to a specific batch checkpoint using git revert, resets Jira ticket statuses, and verifies rollback integrity with tests. - -### Commit - -After each confirmed batch, the `/implement` skill automatically commits and pushes to the remote branch. - ## Available Skills -| Skill | Triggers | Purpose | -|-------|----------|---------| -| **research** | "research", "investigate", "assess solution" | 8-step research → solution drafts | -| **plan** | "plan", "decompose solution" | Architecture, components, risks, tests, epics | -| **decompose** | "decompose", "task decomposition" | Flat numbered task specs + dependency table | -| **implement** | "implement", "start implementation" | Orchestrate task batches with parallel agents | -| **code-review** | "code review", "review code" | 6-phase structured review with findings | -| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow | -| **security** | "security audit", "OWASP" | OWASP-based security testing | -| **deploy** | "deploy", "CI/CD", "containerize", "observability" | Containerization, CI/CD, observability, deployment procedures | -| **retrospective** | "retrospective", "retro", "metrics review" | Collect metrics, analyze trends, produce improvement report | +| Skill | Triggers | Output | +|-------|----------|--------| +| **research** | "research", "investigate" | `_docs/01_solution/` | +| **plan** | "plan", "decompose solution" | `_docs/02_plans/` | +| **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/` | +| **implement** | "implement", "start implementation" | `_docs/03_implementation/` | +| **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS | +| **refactor** | "refactor", "improve code" | `_docs/04_refactoring/` | +| **security** | "security audit", "OWASP" | Security findings report | +| **deploy** | "deploy", "CI/CD", "observability" | `_docs/02_plans/deployment/` | +| **retrospective** | "retrospective", "retro" | `_docs/05_metrics/` | +| **rollback** | "rollback", "revert batch" | `_docs/03_implementation/rollback_report.md` | + +## Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `implementer` | Subagent | Implements a single task. Launched by `/implement`. | ## Project Folder Structure ``` _docs/ -├── 00_problem/ -│ ├── problem.md -│ ├── restrictions.md -│ ├── acceptance_criteria.md -│ ├── input_data/ -│ └── security_approach.md -├── 00_research/ -│ ├── 00_ac_assessment.md -│ ├── 00_question_decomposition.md -│ ├── 01_source_registry.md -│ ├── 02_fact_cards.md -│ ├── 03_comparison_framework.md -│ ├── 04_reasoning_chain.md -│ └── 05_validation_log.md -├── 01_solution/ -│ ├── solution_draft01.md -│ ├── solution_draft02.md -│ ├── solution.md -│ ├── tech_stack.md -│ └── security_analysis.md +├── 00_problem/ — problem definition, restrictions, AC, input data +├── 00_research/ — intermediate research artifacts +├── 01_solution/ — solution drafts, tech stack, security analysis ├── 02_plans/ │ ├── architecture.md │ ├── system-flows.md │ ├── data_model.md │ ├── risk_mitigations.md -│ ├── components/ -│ │ └── [##]_[name]/ -│ │ ├── description.md -│ │ └── tests.md +│ ├── components/[##]_[name]/ — description.md + tests.md per component │ ├── common-helpers/ -│ ├── integration_tests/ -│ │ ├── environment.md -│ │ ├── test_data.md -│ │ ├── functional_tests.md -│ │ ├── non_functional_tests.md -│ │ └── traceability_matrix.md -│ ├── deployment/ -│ │ ├── containerization.md -│ │ ├── ci_cd_pipeline.md -│ │ ├── environment_strategy.md -│ │ ├── observability.md -│ │ └── deployment_procedures.md +│ ├── integration_tests/ — environment, test data, functional, non-functional, traceability +│ ├── deployment/ — containerization, CI/CD, environments, observability, procedures │ ├── diagrams/ │ └── FINAL_report.md -├── 02_tasks/ -│ ├── [JIRA-ID]_initial_structure.md -│ ├── [JIRA-ID]_[short_name].md -│ ├── ... -│ └── _dependencies_table.md -├── 03_implementation/ -│ ├── batch_01_report.md -│ ├── batch_02_report.md -│ ├── ... -│ └── FINAL_implementation_report.md -├── 04_refactoring/ -│ ├── baseline_metrics.md -│ ├── discovery/ -│ ├── analysis/ -│ ├── test_specs/ -│ ├── coupling_analysis.md -│ ├── execution_log.md -│ ├── hardening/ -│ └── FINAL_report.md -└── 05_metrics/ - └── retro_[date].md +├── 02_tasks/ — [JIRA-ID]_[name].md + _dependencies_table.md +├── 03_implementation/ — batch reports, rollback report, FINAL report +├── 04_refactoring/ — baseline, discovery, analysis, execution, hardening +└── 05_metrics/ — retro_[YYYY-MM-DD].md ``` -## Implementation Tools +## Standalone Mode -| Tool | Type | Purpose | -|------|------|---------| -| `implementer` | Subagent | Implements a single task from its spec. Launched by /implement. | -| `/implement` | Skill | Orchestrates all tasks: dependency batching, parallel agents, code review. | -| `/code-review` | Skill | Multi-phase code review with structured findings. | -| `/deploy` | Skill | Containerization, CI/CD, observability, deployment procedures. | -| `/retrospective` | Skill | Collect metrics, analyze trends, produce improvement reports. | -| `/rollback` | Command | Revert to a batch checkpoint with Jira status reset. | - -## Automations (Planned) - -Future automations to explore (Cursor Automations, launched March 2026): -- PR review: trigger code-review skill on PR open (start with Bugbot — read-only, comments only) -- Security scan: trigger security skill on push to main/dev -- Nightly: run integration tests on schedule - -Status: experimental — validate with Bugbot first before adding write-heavy automations. - -## Standalone Mode (Reference) - -Only `research` and `refactor` support standalone mode by passing an explicit file: +`research` and `refactor` support standalone mode — output goes to `_standalone/` (git-ignored): ``` /research @my_problem.md /refactor @some_component.md ``` -Output goes to `_standalone/` (git-ignored) instead of `_docs/`. Standalone mode relaxes guardrails — only the provided file is required; restrictions and acceptance criteria are optional. - ## Single Component Mode (Decompose) -Decompose supports single component mode when given a component file from within `_docs/02_plans/components/`: - ``` /decompose @_docs/02_plans/components/03_parser/description.md ``` -This appends tasks for that component to the existing `_docs/02_tasks/` directory without running bootstrap or cross-verification steps. +Appends tasks for that component to `_docs/02_tasks/` without running bootstrap or cross-verification. diff --git a/.cursor/commands/rollback.md b/.cursor/commands/rollback.md deleted file mode 100644 index 0e39bb9..0000000 --- a/.cursor/commands/rollback.md +++ /dev/null @@ -1,54 +0,0 @@ -# Implementation Rollback - -## Role -You are a DevOps engineer performing a controlled rollback of implementation batches. - -## Input -- User specifies a target batch number or commit hash to roll back to -- If not specified, present the list of available batch checkpoints and ask - -## Process - -1. Read `_docs/03_implementation/batch_*_report.md` files to identify all batch checkpoints with their commit hashes -2. Present batch list to user with: batch number, date, tasks included, commit hash -3. Determine which commits need to be reverted (all commits after the target batch) -4. For each commit to revert (in reverse chronological order): - - Run `git revert --no-edit` - - Verify no merge conflicts; if conflicts occur, ask user for resolution -5. Run the full test suite to verify rollback integrity -6. If tests fail, report failures and ask user how to proceed -7. Reset Jira ticket statuses for all reverted tasks back to "To Do" via Jira MCP -8. Commit the revert with message: `[ROLLBACK] Reverted to batch [N]: [task list]` - -## Output - -Write `_docs/03_implementation/rollback_report.md`: - -```markdown -# Rollback Report - -**Date**: [YYYY-MM-DD] -**Target**: Batch [N] (commit [hash]) -**Reverted Batches**: [list] - -## Reverted Tasks - -| Task | Batch | Status Before | Status After | -|------|-------|--------------|-------------| -| [JIRA-ID] | [batch #] | In Testing | To Do | - -## Test Results -- [pass/fail count] - -## Jira Updates -- [list of ticket transitions] - -## Notes -- [any conflicts, manual steps, or issues encountered] -``` - -## Safety Rules -- Never force-push; always use `git revert` to preserve history -- Always run tests after rollback -- Always update Jira statuses for reverted tasks -- If rollback fails midway, stop and report — do not leave the codebase in a partial state diff --git a/.cursor/skills/retrospective/SKILL.md b/.cursor/skills/retrospective/SKILL.md index 414c121..0f04f25 100644 --- a/.cursor/skills/retrospective/SKILL.md +++ b/.cursor/skills/retrospective/SKILL.md @@ -160,15 +160,15 @@ Present the report summary to the user. ``` ┌────────────────────────────────────────────────────────────────┐ -│ Retrospective (3-Step Method) │ +│ Retrospective (3-Step Method) │ ├────────────────────────────────────────────────────────────────┤ -│ PREREQ: batch reports exist in _docs/03_implementation/ │ +│ PREREQ: batch reports exist in _docs/03_implementation/ │ │ │ -│ 1. Collect Metrics → parse batch reports, compute metrics │ -│ 2. Analyze Trends → patterns, comparison, improvement areas │ +│ 1. Collect Metrics → parse batch reports, compute metrics │ +│ 2. Analyze Trends → patterns, comparison, improvement areas │ │ 3. Produce Report → _docs/05_metrics/retro_[date].md │ ├────────────────────────────────────────────────────────────────┤ -│ Principles: Data-driven · Actionable · Cumulative │ -│ Non-judgmental · Save immediately │ +│ Principles: Data-driven · Actionable · Cumulative │ +│ Non-judgmental · Save immediately │ └────────────────────────────────────────────────────────────────┘ ``` diff --git a/.cursor/skills/rollback/SKILL.md b/.cursor/skills/rollback/SKILL.md new file mode 100644 index 0000000..064ef58 --- /dev/null +++ b/.cursor/skills/rollback/SKILL.md @@ -0,0 +1,130 @@ +--- +name: rollback +description: | + Revert implementation to a specific batch checkpoint using git revert, reset Jira ticket statuses, + verify rollback integrity with tests, and produce a rollback report. + Trigger phrases: + - "rollback", "revert", "revert batch" + - "undo implementation", "roll back to batch" +category: build +tags: [rollback, revert, recovery, implementation] +disable-model-invocation: true +--- + +# Implementation Rollback + +Revert the codebase to a specific batch checkpoint, reset Jira statuses for reverted tasks, and verify integrity. + +## Core Principles + +- **Preserve history**: always use `git revert`, never force-push +- **Verify after revert**: run the full test suite after every rollback +- **Update tracking**: reset Jira ticket statuses for all reverted tasks +- **Atomic rollback**: if rollback fails midway, stop and report — do not leave the codebase in a partial state +- **Ask, don't assume**: if the target batch is ambiguous, present options and ask + +## Context Resolution + +- IMPL_DIR: `_docs/03_implementation/` +- Batch reports: `IMPL_DIR/batch_*_report.md` + +## Prerequisite Checks (BLOCKING) + +1. IMPL_DIR exists and contains at least one `batch_*_report.md` — **STOP if missing** +2. Git working tree is clean (no uncommitted changes) — **STOP if dirty**, ask user to commit or stash + +## Input + +- User specifies a target batch number or commit hash +- If not specified, present the list of available batch checkpoints and ask + +## Workflow + +### Step 1: Identify Checkpoints + +1. Read all `batch_*_report.md` files from IMPL_DIR +2. Extract: batch number, date, tasks included, commit hash, code review verdict +3. Present batch list to user + +**BLOCKING**: User must confirm which batch to roll back to. + +### Step 2: Revert Commits + +1. Determine which commits need to be reverted (all commits after the target batch) +2. For each commit in reverse chronological order: + - Run `git revert --no-edit` + - If merge conflicts occur: present conflicts and ask user for resolution +3. If any revert fails and cannot be resolved, abort the rollback sequence with `git revert --abort` and report + +### Step 3: Verify Integrity + +1. Run the full test suite +2. If tests fail: report failures to user, ask how to proceed (fix or abort) +3. If tests pass: continue + +### Step 4: Update Jira + +1. Identify all tasks from reverted batches +2. Reset each task's Jira ticket status to "To Do" via Jira MCP + +### Step 5: Finalize + +1. Commit with message: `[ROLLBACK] Reverted to batch [N]: [task list]` +2. Write rollback report to `IMPL_DIR/rollback_report.md` + +## Output + +Write `_docs/03_implementation/rollback_report.md`: + +```markdown +# Rollback Report + +**Date**: [YYYY-MM-DD] +**Target**: Batch [N] (commit [hash]) +**Reverted Batches**: [list] + +## Reverted Tasks + +| Task | Batch | Status Before | Status After | +|------|-------|--------------|-------------| +| [JIRA-ID] | [batch #] | In Testing | To Do | + +## Test Results +- [pass/fail count] + +## Jira Updates +- [list of ticket transitions] + +## Notes +- [any conflicts, manual steps, or issues encountered] +``` + +## Escalation Rules + +| Situation | Action | +|-----------|--------| +| No batch reports exist | **STOP** — nothing to roll back | +| Uncommitted changes in working tree | **STOP** — ask user to commit or stash | +| Merge conflicts during revert | **ASK user** for resolution | +| Tests fail after rollback | **ASK user** — fix or abort | +| Rollback fails midway | Abort with `git revert --abort`, report to user | + +## Methodology Quick Reference + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Rollback (5-Step Method) │ +├────────────────────────────────────────────────────────────────┤ +│ PREREQ: batch reports exist, clean working tree │ +│ │ +│ 1. Identify Checkpoints → present batch list │ +│ [BLOCKING: user confirms target batch] │ +│ 2. Revert Commits → git revert per commit │ +│ 3. Verify Integrity → run full test suite │ +│ 4. Update Jira → reset statuses to "To Do" │ +│ 5. Finalize → commit + rollback_report.md │ +├────────────────────────────────────────────────────────────────┤ +│ Principles: Preserve history · Verify after revert │ +│ Atomic rollback · Ask don't assume │ +└────────────────────────────────────────────────────────────────┘ +```