diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..5008ddf Binary files /dev/null and b/.DS_Store differ diff --git a/.cursor/README.md b/.cursor/README.md new file mode 100644 index 0000000..01623a0 --- /dev/null +++ b/.cursor/README.md @@ -0,0 +1,179 @@ +## Developer TODO (Project Mode) + +### BUILD (green-field or new features) + +``` +1. Create _docs/00_problem/ — describe what you're building + - problem.md (required) + - restrictions.md (required) + - acceptance_criteria.md (required) + - security_approach.md (optional) + +2. /research — produces solution drafts in _docs/01_solution/ + Run multiple times: Mode A → draft, Mode B → assess & revise + Finalize as solution.md + +3. /plan — architecture, components, risks, tests → _docs/02_plans/ + +4. /decompose — feature specs, implementation order → _docs/02_tasks/ + +5. /implement-initial — scaffold project from initial_structure.md (once) + +6. /implement-wave — implement next wave of features (repeat per wave) + +7. /implement-code-review — review implemented code (after each wave or at the end) + +8. /implement-black-box-tests — E2E tests via Docker consumer app (after all waves) + +9. commit & push +``` + +### SHIP (deploy and operate) + +``` +10. /implement-cicd — validate/enhance CI/CD pipeline +11. /deploy — deployment strategy per environment +12. /observability — monitoring, logging, alerting plan +``` + +### EVOLVE (maintenance and improvement) + +``` +13. /refactor — structured refactoring (skill, 6-phase workflow) +``` + +## Implementation Flow + +### `/implement-initial` + +Reads `_docs/02_tasks//initial_structure.md` and scaffolds the project skeleton: folder structure, shared models, interfaces, stubs, .gitignore, .env.example, CI/CD config, DB migrations setup, test structure. + +Run once after decompose. + +### `/implement-wave` + +Reads `SUMMARY.md` and `cross_dependencies.md` from `_docs/02_tasks//`. + +1. Detects which features are already implemented +2. Identifies the next wave (phase) of independent features +3. Presents the wave for confirmation (blocks until user confirms) +4. Launches parallel `implementer` subagents (max 4 concurrent; same-component features run sequentially) +5. Runs tests, reports results +6. Suggests commit + +Repeat `/implement-wave` until all phases are done. + +### `/implement-code-review` + +Reviews implemented code against specs. Reports issues by type (Bug/Security/Performance/Style/Debt) with priorities and suggested fixes. + +### `/implement-black-box-tests` + +Reads `_docs/02_plans//e2e_test_infrastructure.md` (produced by plan skill). Builds a separate Docker-based consumer app that exercises the system as a black box — no internal imports, no direct DB access. Runs E2E scenarios, produces a CSV test report. + +Run after all waves are done. + +### `/implement-cicd` + +Reviews existing CI/CD pipeline configuration, validates all stages work, optimizes performance (parallelization, caching), ensures quality gates are enforced (coverage, linting, security scanning). + +Run after `/implement-initial` or after all waves. + +### `/deploy` + +Defines deployment strategy per environment: deployment procedures, rollback procedures, health checks, deployment checklist. Outputs `_docs/02_components/deployment_strategy.md`. + +Run before first production release. + +### `/observability` + +Plans logging strategy, metrics collection, distributed tracing, alerting rules, and dashboards. Outputs `_docs/02_components/observability_plan.md`. + +Run before first production release. + +### Commit + +After each wave or review — standard `git add && git commit`. The wave command suggests a commit message. + +## 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" | Feature specs + implementation order | +| **refactor** | "refactor", "refactoring", "improve code" | 6-phase structured refactoring workflow | +| **security** | "security audit", "OWASP" | OWASP-based security testing | + +## Project Folder Structure + +``` +_docs/ +├── 00_problem/ +│ ├── problem.md +│ ├── restrictions.md +│ ├── acceptance_criteria.md +│ └── security_approach.md +├── 01_solution/ +│ ├── solution_draft01.md +│ ├── solution_draft02.md +│ ├── solution.md +│ ├── tech_stack.md +│ └── security_analysis.md +├── 01_research/ +│ └── / +├── 02_plans/ +│ └── / +│ ├── architecture.md +│ ├── system-flows.md +│ ├── components/ +│ └── FINAL_report.md +├── 02_tasks/ +│ └── / +│ ├── initial_structure.md +│ ├── cross_dependencies.md +│ ├── SUMMARY.md +│ └── [##]_[component]/ +│ └── [##].[##]_feature_[name].md +└── 04_refactoring/ + ├── baseline_metrics.md + ├── discovery/ + ├── analysis/ + ├── test_specs/ + ├── coupling_analysis.md + ├── execution_log.md + ├── hardening/ + └── FINAL_report.md +``` + +## Implementation Tools + +| Tool | Type | Purpose | +|------|------|---------| +| `implementer` | Subagent | Implements a single feature from its spec. Launched by implement-wave. | +| `/implement-initial` | Command | Scaffolds project skeleton from `initial_structure.md`. Run once. | +| `/implement-wave` | Command | Detects next wave, launches parallel implementers. Repeatable. | +| `/implement-code-review` | Command | Reviews code against specs. | +| `/implement-black-box-tests` | Command | E2E tests via Docker consumer app. After all waves. | +| `/implement-cicd` | Command | Validate and enhance CI/CD pipeline. | +| `/deploy` | Command | Plan deployment strategy per environment. | +| `/observability` | Command | Plan logging, metrics, tracing, alerting. | + +## Standalone Mode (Reference) + +Any skill can run in standalone mode by passing an explicit file: + +``` +/research @my_problem.md +/plan @my_design.md +/decompose @some_spec.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 decompose is also supported: + +``` +/decompose @_docs/02_plans//components/03_parser/description.md +``` diff --git a/.cursor/agents/implementer.md b/.cursor/agents/implementer.md new file mode 100644 index 0000000..b16c7d1 --- /dev/null +++ b/.cursor/agents/implementer.md @@ -0,0 +1,49 @@ +--- +name: implementer +description: | + Implements a single feature from its spec file. Use when implementing features from _docs/02_tasks/. + Reads the feature spec, analyzes the codebase, implements the feature with tests, and verifies acceptance criteria. +--- + +You are a professional software developer implementing a single feature. + +## Input + +You receive a path to a feature spec file (e.g., `_docs/02_tasks//[##]_[name]/[##].[##]_feature_[name].md`). + +## Context + +Read these files for project context: +- `_docs/00_problem/problem.md` +- `_docs/00_problem/restrictions.md` +- `_docs/00_problem/acceptance_criteria.md` +- `_docs/01_solution/solution.md` + +## Process + +1. Read the feature spec thoroughly — understand acceptance criteria, scope, constraints +2. Analyze the existing codebase: conventions, patterns, related code, shared interfaces +3. Research best implementation approaches for the tech stack if needed +4. If the feature has a dependency on an unimplemented component, create a temporary mock +5. Implement the feature following existing code conventions +6. Implement error handling per the project's defined strategy +7. Implement unit tests (use //Arrange //Act //Assert comments) +8. Implement integration tests — analyze existing tests, add to them or create new +9. Run all tests, fix any failures +10. Verify the implementation satisfies every acceptance criterion from the spec + +## After completion + +Report: +- What was implemented +- Which acceptance criteria are satisfied +- Test results (passed/failed) +- Any mocks created for unimplemented dependencies +- Any concerns or deviations from the spec + +## Principles + +- Follow SOLID, KISS, DRY +- Dumb code, smart data +- No unnecessary comments or logs (only exceptions) +- Ask if requirements are ambiguous — do not assume diff --git a/.roo/commands/3.35_plan_deployment.md b/.cursor/commands/deploy.md similarity index 99% rename from .roo/commands/3.35_plan_deployment.md rename to .cursor/commands/deploy.md index 304fa53..4605aa2 100644 --- a/.roo/commands/3.35_plan_deployment.md +++ b/.cursor/commands/deploy.md @@ -69,4 +69,3 @@ Store output to `_docs/02_components/deployment_strategy.md` - Zero-downtime deployments for production - Always have a rollback plan - Ask questions about infrastructure constraints - diff --git a/.cursor/commands/implement-black-box-tests.md b/.cursor/commands/implement-black-box-tests.md new file mode 100644 index 0000000..d880d47 --- /dev/null +++ b/.cursor/commands/implement-black-box-tests.md @@ -0,0 +1,45 @@ +# Implement E2E Black-Box Tests + +Build a separate Docker-based consumer application that exercises the main system as a black box, validating end-to-end use cases. + +## Input +- E2E test infrastructure spec: `_docs/02_plans//e2e_test_infrastructure.md` (produced by plan skill Step 4b) + +## Context +- Problem description: `@_docs/00_problem/problem.md` +- Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md` +- Solution: `@_docs/01_solution/solution.md` +- Architecture: `@_docs/02_plans//architecture.md` + +## Role +You are a professional QA engineer and developer + +## Task +- Read the E2E test infrastructure spec thoroughly +- Build the Docker test environment: + - Create docker-compose.yml with all services (system under test, test DB, consumer app, dependency mocks) + - Configure networks and volumes per spec +- Implement the consumer application: + - Separate project/folder that communicates with the main system only through its public interfaces + - No internal imports from the main system, no direct DB access + - Use the tech stack and entry point defined in the spec +- Implement each E2E test scenario from the spec: + - Check existing E2E tests; update if a similar test already exists + - Prepare seed data and fixtures per the test data management section + - Implement teardown/cleanup procedures +- Run the full E2E suite via `docker compose up` +- If tests fail: + - Fix issues iteratively until all pass + - If a failure is caused by missing external data, API access, or environment config, ask the user +- Ensure the E2E suite integrates into the CI pipeline per the spec +- Produce a CSV test report (test ID, name, execution time, result, error message) at the output path defined in the spec + +## Safety Rules +- The consumer app must treat the main system as a true black box +- Never import internal modules or access the main system's database directly +- Docker environment must be self-contained — no host dependencies beyond Docker itself +- If external services need mocking, implement mock/stub services as Docker containers + +## Notes +- Ask questions if the spec is ambiguous or incomplete +- If `e2e_test_infrastructure.md` is missing, stop and inform the user to run the plan skill first diff --git a/.roo/commands/3.30_implement_cicd.md b/.cursor/commands/implement-cicd.md similarity index 100% rename from .roo/commands/3.30_implement_cicd.md rename to .cursor/commands/implement-cicd.md diff --git a/.roo/commands/3.20_implement_code_review.md b/.cursor/commands/implement-code-review.md similarity index 99% rename from .roo/commands/3.20_implement_code_review.md rename to .cursor/commands/implement-code-review.md index 4c0f231..ef99112 100644 --- a/.roo/commands/3.20_implement_code_review.md +++ b/.cursor/commands/implement-code-review.md @@ -36,4 +36,3 @@ ## Notes - Can also use Cursor's built-in review feature - Focus on critical issues first - diff --git a/.cursor/commands/implement-initial.md b/.cursor/commands/implement-initial.md new file mode 100644 index 0000000..9407e3c --- /dev/null +++ b/.cursor/commands/implement-initial.md @@ -0,0 +1,53 @@ +# Implement Initial Structure + +## Input +- Structure plan: `_docs/02_tasks//initial_structure.md` (produced by decompose skill) + +## Context +- Problem description: `@_docs/00_problem/problem.md` +- Restrictions: `@_docs/00_problem/restrictions.md` +- Solution: `@_docs/01_solution/solution.md` + +## Role +You are a professional software architect + +## Task +- Read carefully the structure plan in `initial_structure.md` +- Execute the plan — create the project skeleton: + - DTOs and shared models + - Component interfaces + - Empty implementations (stubs) + - Helpers — empty implementations or interfaces +- Add .gitignore appropriate for the project's language/framework +- Add .env.example with required environment variables +- Configure CI/CD pipeline per the structure plan stages +- Apply environment strategy (dev, staging, production) per the structure plan +- Add database migration setup if applicable +- Add README.md, describe the project based on the solution +- Create test folder structure per the structure plan +- Configure branch protection rules recommendations + +## Example +The structure should roughly look like this (varies by tech stack): + - .gitignore + - .env.example + - .github/workflows/ (or .gitlab-ci.yml or azure-pipelines.yml) + - api/ + - components/ + - component1_folder/ + - component2_folder/ + - db/ + - migrations/ + - helpers/ + - models/ + - tests/ + - unit/ + - integration/ + - test_data/ + +Semantically coherent components may have their own project or subfolder. Common interfaces can be in a shared layer or per-component — follow language conventions. + +## Notes +- Follow SOLID, KISS, DRY +- Follow conventions of the project's programming language +- Ask as many questions as needed diff --git a/.cursor/commands/implement-wave.md b/.cursor/commands/implement-wave.md new file mode 100644 index 0000000..11c517a --- /dev/null +++ b/.cursor/commands/implement-wave.md @@ -0,0 +1,62 @@ +# Implement Next Wave + +Identify the next batch of independent features and implement them in parallel using the implementer subagent. + +## Prerequisites +- Project scaffolded (`/implement-initial` completed) +- `_docs/02_tasks//SUMMARY.md` exists +- `_docs/02_tasks//cross_dependencies.md` exists + +## Wave Sizing +- One wave = one phase from SUMMARY.md (features whose dependencies are all satisfied) +- Max 4 subagents run concurrently; features in the same component run sequentially +- If a phase has more than 8 features or more than 20 complexity points, suggest splitting into smaller waves and let the user cherry-pick which features to include + +## Task + +1. **Read the implementation plan** + - Read `SUMMARY.md` for the phased implementation order + - Read `cross_dependencies.md` for the dependency graph + +2. **Detect current progress** + - Analyze the codebase to determine which features are already implemented + - Match implemented code against feature specs in `_docs/02_tasks//` + - Identify the next incomplete wave/phase from the implementation order + +3. **Present the wave** + - List all features in this wave with their complexity points + - Show which component each feature belongs to + - Confirm total features and estimated complexity + - If the phase exceeds 8 features or 20 complexity points, recommend splitting and let user select a subset + - **BLOCKING**: Do NOT proceed until user confirms + +4. **Launch parallel implementation** + - For each feature in the wave, launch an `implementer` subagent in background + - Each subagent receives the path to its feature spec file + - Features within different components can run in parallel + - Features within the same component should run sequentially to avoid file conflicts + +5. **Monitor and report** + - Wait for all subagents to complete + - Collect results from each: what was implemented, test results, any issues + - Run the full test suite + - Report summary: + - Features completed successfully + - Features that failed or need manual attention + - Test results (passed/failed/skipped) + - Any mocks created for future-wave dependencies + +6. **Post-wave actions** + - Suggest: `git add . && git commit` with a wave-level commit message + - If all features passed: "Ready for next wave. Run `/implement-wave` again." + - If some failed: "Fix the failing features before proceeding to the next wave." + +## Safety Rules +- Never launch features whose dependencies are not yet implemented +- Features within the same component run sequentially, not in parallel +- If a subagent fails, do NOT retry automatically — report and let user decide +- Always run tests after the wave completes, before suggesting commit + +## Notes +- Ask questions if the implementation order is ambiguous +- If SUMMARY.md or cross_dependencies.md is missing, stop and inform the user to run the decompose skill first diff --git a/.roo/commands/3.42_plan_observability.md b/.cursor/commands/observability.md similarity index 99% rename from .roo/commands/3.42_plan_observability.md rename to .cursor/commands/observability.md index 60c098d..a9be136 100644 --- a/.roo/commands/3.42_plan_observability.md +++ b/.cursor/commands/observability.md @@ -120,4 +120,3 @@ Store output to `_docs/02_components/observability_plan.md` - Balance verbosity with cost - Ensure PII is not logged - Plan for log rotation and retention - diff --git a/.cursor/rules/coderule.mdc b/.cursor/rules/coderule.mdc new file mode 100644 index 0000000..133ec59 --- /dev/null +++ b/.cursor/rules/coderule.mdc @@ -0,0 +1,22 @@ +--- +description: Coding rules +alwaysApply: true +--- +# Coding preferences +- Always prefer simple solution +- Generate concise code +- Do not put comments in the code +- Do not put logs unless it is an exception, or was asked specifically +- Do not put code annotations unless it was asked specifically +- Write code that takes into account the different environments: development, production +- You are careful to make changes that are requested or you are confident the changes are well understood and related to the change being requested +- Mocking data is needed only for tests, never mock data for dev or prod env +- When you add new libraries or dependencies make sure you are using the same version of it as other parts of the code + +- Focus on the areas of code relevant to the task +- Do not touch code that is unrelated to the task +- Always think about what other methods and areas of code might be affected by the code changes +- When you think you are done with changes, run tests and make sure they are not broken +- Do not rename any databases or tables or table columns without confirmation. Avoid such renaming if possible. +- Do not create diagrams unless I ask explicitly +- Make sure we don't commit binaries, create and keep .gitignore up to date and delete binaries after you are done with the task diff --git a/.cursor/rules/techstackrule.mdc b/.cursor/rules/techstackrule.mdc new file mode 100644 index 0000000..7d2ee2b --- /dev/null +++ b/.cursor/rules/techstackrule.mdc @@ -0,0 +1,9 @@ +--- +description: Techstack +alwaysApply: true +--- +# Tech Stack +- Using Postgres database +- Depending on task, for backend prefer .Net or Python. Could be RUST for more specific things. +- For Frontend, use React with Tailwind css (or even plain css, if it is a simple project) +- document api with OpenAPI \ No newline at end of file diff --git a/.cursor/skills/decompose/SKILL.md b/.cursor/skills/decompose/SKILL.md new file mode 100644 index 0000000..b312e6d --- /dev/null +++ b/.cursor/skills/decompose/SKILL.md @@ -0,0 +1,281 @@ +--- +name: decompose +description: | + Decompose planned components into atomic implementable features with bootstrap structure plan. + 4-step workflow: bootstrap structure plan, feature decomposition, cross-component verification, and Jira task creation. + Supports project mode (_docs/ structure), single component mode, and standalone mode (@file.md). + Trigger phrases: + - "decompose", "decompose features", "feature decomposition" + - "task decomposition", "break down components" + - "prepare for implementation" +disable-model-invocation: true +--- + +# Feature Decomposition + +Decompose planned components into atomic, implementable feature specs with a bootstrap structure plan through a systematic workflow. + +## Core Principles + +- **Atomic features**: each feature does one thing; if it exceeds 5 complexity points, split it +- **Behavioral specs, not implementation plans**: describe what the system should do, not how to build it +- **Save immediately**: write artifacts to disk after each component; never accumulate unsaved work +- **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding +- **Plan, don't code**: this workflow produces documents and Jira tasks, never implementation code + +## Context Resolution + +Determine the operating mode based on invocation before any other logic runs. + +**Full project mode** (no explicit input file provided): +- PLANS_DIR: `_docs/02_plans/` +- TASKS_DIR: `_docs/02_tasks/` +- Reads from: `_docs/00_problem/`, `_docs/01_solution/`, PLANS_DIR +- Runs Step 1 (bootstrap) + Step 2 (all components) + Step 3 (cross-verification) + Step 4 (Jira) + +**Single component mode** (provided file is within `_docs/02_plans/` and inside a `components/` subdirectory): +- PLANS_DIR: `_docs/02_plans/` +- TASKS_DIR: `_docs/02_tasks/` +- Derive ``, component number, and component name from the file path +- Ask user for the parent Epic ID +- Runs Step 2 (that component only) + Step 4 (Jira) +- Overwrites existing feature files in that component's TASKS_DIR subdirectory + +**Standalone mode** (explicit input file provided, not within `_docs/02_plans/`): +- INPUT_FILE: the provided file (treated as a component spec) +- Derive `` from the input filename (without extension) +- TASKS_DIR: `_standalone//tasks/` +- Guardrails relaxed: only INPUT_FILE must exist and be non-empty +- Ask user for the parent Epic ID +- Runs Step 2 (that component only) + Step 4 (Jira) + +Announce the detected mode and resolved paths to the user before proceeding. + +## Input Specification + +### Required Files + +**Full project mode:** + +| File | Purpose | +|------|---------| +| `_docs/00_problem/problem.md` | Problem description and context | +| `_docs/00_problem/restrictions.md` | Constraints and limitations (if available) | +| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria (if available) | +| `_docs/01_solution/solution.md` | Finalized solution | +| `PLANS_DIR//architecture.md` | Architecture from plan skill | +| `PLANS_DIR//system-flows.md` | System flows from plan skill | +| `PLANS_DIR//components/[##]_[name]/description.md` | Component specs from plan skill | + +**Single component mode:** + +| File | Purpose | +|------|---------| +| The provided component `description.md` | Component spec to decompose | +| Corresponding `tests.md` in the same directory (if available) | Test specs for context | + +**Standalone mode:** + +| File | Purpose | +|------|---------| +| INPUT_FILE (the provided file) | Component spec to decompose | + +### Prerequisite Checks (BLOCKING) + +**Full project mode:** +1. At least one `/` directory exists under PLANS_DIR with `architecture.md` and `components/` — **STOP if missing** +2. If multiple topics exist, ask user which one to decompose +3. Create TASKS_DIR if it does not exist +4. If `TASKS_DIR//` already exists, ask user: **resume from last checkpoint or start fresh?** + +**Single component mode:** +1. The provided component file exists and is non-empty — **STOP if missing** +2. Create the component's subdirectory under TASKS_DIR if it does not exist + +**Standalone mode:** +1. INPUT_FILE exists and is non-empty — **STOP if missing** +2. Create TASKS_DIR if it does not exist + +## Artifact Management + +### Directory Structure + +``` +TASKS_DIR// +├── initial_structure.md (Step 1, full mode only) +├── cross_dependencies.md (Step 3, full mode only) +├── SUMMARY.md (final) +├── [##]_[component_name]/ +│ ├── [##].[##]_feature_[feature_name].md +│ ├── [##].[##]_feature_[feature_name].md +│ └── ... +├── [##]_[component_name]/ +│ └── ... +└── ... +``` + +### Save Timing + +| Step | Save immediately after | Filename | +|------|------------------------|----------| +| Step 1 | Bootstrap structure plan complete | `initial_structure.md` | +| Step 2 | Each component decomposed | `[##]_[name]/[##].[##]_feature_[feature_name].md` | +| Step 3 | Cross-component verification complete | `cross_dependencies.md` | +| Step 4 | Jira tasks created | Jira via MCP | +| Final | All steps complete | `SUMMARY.md` | + +### Resumability + +If `TASKS_DIR//` already contains artifacts: + +1. List existing files and match them to the save timing table +2. Identify the last completed component based on which feature files exist +3. Resume from the next incomplete component +4. Inform the user which components are being skipped + +## Progress Tracking + +At the start of execution, create a TodoWrite with all applicable steps. Update status as each step/component completes. + +## Workflow + +### Step 1: Bootstrap Structure Plan (full project mode only) + +**Role**: Professional software architect +**Goal**: Produce `initial_structure.md` describing the project skeleton for implementation +**Constraints**: This is a plan document, not code. The `implement-initial` command executes it. + +1. Read architecture.md, all component specs, and system-flows.md from PLANS_DIR +2. Read problem, solution, and restrictions from `_docs/00_problem/` and `_docs/01_solution/` +3. Research best implementation patterns for the identified tech stack +4. Document the structure plan using `templates/initial-structure.md` + +**Self-verification**: +- [ ] All components have corresponding folders in the layout +- [ ] All inter-component interfaces have DTOs defined +- [ ] CI/CD stages cover build, lint, test, security, deploy +- [ ] Environment strategy covers dev, staging, production +- [ ] Test structure includes unit and integration test locations + +**Save action**: Write `initial_structure.md` + +**BLOCKING**: Present structure plan summary to user. Do NOT proceed until user confirms. + +--- + +### Step 2: Feature Decomposition (all modes) + +**Role**: Professional software architect +**Goal**: Decompose each component into atomic, implementable feature specs +**Constraints**: Behavioral specs only — describe what, not how. No implementation code. + +For each component (or the single provided component): + +1. Read the component's `description.md` and `tests.md` (if available) +2. Decompose into atomic features; create only 1 feature if the component is simple or atomic +3. Split into multiple features only when it is necessary and would be easier to implement +4. Do not create features of other components — only features of the current component +5. Each feature should be atomic, containing 0 APIs or a list of semantically connected APIs +6. Write each feature spec using `templates/feature-spec.md` +7. Estimate complexity per feature (1, 2, 3, 5 points); no feature should exceed 5 points — split if it does +8. Note feature dependencies (within component and cross-component) + +**Self-verification** (per component): +- [ ] Every feature is atomic (single concern) +- [ ] No feature exceeds 5 complexity points +- [ ] Feature dependencies are noted +- [ ] Features cover all interfaces defined in the component spec +- [ ] No features duplicate work from other components + +**Save action**: Write each `[##]_[name]/[##].[##]_feature_[feature_name].md` + +--- + +### Step 3: Cross-Component Verification (full project mode only) + +**Role**: Professional software architect and analyst +**Goal**: Verify feature consistency across all components +**Constraints**: Review step — fix gaps found, do not add new features + +1. Verify feature dependencies across all components are consistent +2. Check no gaps: every interface in architecture.md has features covering it +3. Check no overlaps: features don't duplicate work across components +4. Produce dependency matrix showing cross-component feature dependencies +5. Determine recommended implementation order based on dependencies + +**Self-verification**: +- [ ] Every architecture interface is covered by at least one feature +- [ ] No circular feature dependencies across components +- [ ] Cross-component dependencies are explicitly noted in affected feature specs + +**Save action**: Write `cross_dependencies.md` + +**BLOCKING**: Present cross-component summary to user. Do NOT proceed until user confirms. + +--- + +### Step 4: Jira Tasks (all modes) + +**Role**: Professional product manager +**Goal**: Create Jira tasks from feature specs under the appropriate parent epics +**Constraints**: Be concise — fewer words with the same meaning is better + +1. For each feature spec, create a Jira task following the parsing rules and field mapping from `gen_jira_task_and_branch.md` (skip branch creation and file renaming — those happen during implementation) +2. In full mode: search Jira for epics matching component names/labels to find parent epic IDs +3. In single component mode: use the Epic ID obtained during context resolution +4. In standalone mode: use the Epic ID obtained during context resolution +5. Do NOT create git branches or rename files — that happens during implementation + +**Self-verification**: +- [ ] Every feature has a corresponding Jira task +- [ ] Every task is linked to the correct parent epic +- [ ] Task descriptions match feature spec content + +**Save action**: Jira tasks created via MCP + +--- + +## Summary Report + +After all steps complete, write `SUMMARY.md` using `templates/summary.md` as structure. + +## Common Mistakes + +- **Coding during decomposition**: this workflow produces specs, never code +- **Over-splitting**: don't create many features if the component is simple — 1 feature is fine +- **Features exceeding 5 points**: split them; no feature should be too complex for a single task +- **Cross-component features**: each feature belongs to exactly one component +- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation +- **Creating git branches**: branch creation is an implementation concern, not a decomposition one + +## Escalation Rules + +| Situation | Action | +|-----------|--------| +| Ambiguous component boundaries | ASK user | +| Feature complexity exceeds 5 points after splitting | ASK user | +| Missing component specs in PLANS_DIR | ASK user | +| Cross-component dependency conflict | ASK user | +| Jira epic not found for a component | ASK user for Epic ID | +| Component naming | PROCEED, confirm at next BLOCKING gate | + +## Methodology Quick Reference + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Feature Decomposition (4-Step Method) │ +├────────────────────────────────────────────────────────────────┤ +│ CONTEXT: Resolve mode (full / single component / standalone) │ +│ 1. Bootstrap Structure → initial_structure.md (full only) │ +│ [BLOCKING: user confirms structure] │ +│ 2. Feature Decompose → [##]_[name]/[##].[##]_feature_* │ +│ 3. Cross-Verification → cross_dependencies.md (full only) │ +│ [BLOCKING: user confirms dependencies] │ +│ 4. Jira Tasks → Jira via MCP │ +│ ───────────────────────────────────────────────── │ +│ Summary → SUMMARY.md │ +├────────────────────────────────────────────────────────────────┤ +│ Principles: Atomic features · Behavioral specs · Save now │ +│ Ask don't assume · Plan don't code │ +└────────────────────────────────────────────────────────────────┘ +``` diff --git a/.cursor/skills/decompose/templates/feature-spec.md b/.cursor/skills/decompose/templates/feature-spec.md new file mode 100644 index 0000000..bc0ef6e --- /dev/null +++ b/.cursor/skills/decompose/templates/feature-spec.md @@ -0,0 +1,108 @@ +# Feature Specification Template + +Create a focused behavioral specification that describes **what** the system should do, not **how** it should be built. +Save as `TASKS_DIR//[##]_[component_name]/[##].[##]_feature_[feature_name].md`. + +--- + +```markdown +# [Feature Name] + +**Status**: Draft | **Date**: [YYYY-MM-DD] | **Feature**: [Brief Feature Description] +**Complexity**: [1|2|3|5] points +**Dependencies**: [List dependent features or "None"] +**Component**: [##]_[component_name] + +## Problem + +Clear, concise statement of the problem users are facing. + +## Outcome + +- Measurable or observable goal 1 +- Measurable or observable goal 2 + +## Scope + +### Included +- What's in scope for this feature + +### Excluded +- Explicitly what's NOT in scope + +## Acceptance Criteria + +**AC-1: [Title]** +Given [precondition] +When [action] +Then [expected result] + +**AC-2: [Title]** +Given [precondition] +When [action] +Then [expected result] + +## Non-Functional Requirements + +**Performance** +- [requirement if relevant] + +**Compatibility** +- [requirement if relevant] + +**Reliability** +- [requirement if relevant] + +## Unit Tests + +| AC Ref | What to Test | Required Outcome | +|--------|-------------|-----------------| +| AC-1 | [test subject] | [expected result] | + +## Integration Tests + +| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References | +|--------|------------------------|-------------|-------------------|----------------| +| AC-1 | [setup] | [test subject] | [expected behavior] | [NFR if any] | + +## Constraints + +- [Architectural pattern constraint if critical] +- [Technical limitation] +- [Integration requirement] + +## Risks & Mitigation + +**Risk 1: [Title]** +- *Risk*: [Description] +- *Mitigation*: [Approach] +``` + +--- + +## Complexity Points Guide + +- 1 point: Trivial, self-contained, no dependencies +- 2 points: Non-trivial, low complexity, minimal coordination +- 3 points: Multi-step, moderate complexity, potential alignment needed +- 5 points: Difficult, interconnected logic, medium-high risk +- 8 points: Too complex — split into smaller features + +## Output Guidelines + +**DO:** +- Focus on behavior and user experience +- Use clear, simple language +- Keep acceptance criteria testable (Gherkin format) +- Include realistic scope boundaries +- Write from the user's perspective +- Include complexity estimation +- Note dependencies on other features + +**DON'T:** +- Include implementation details (file paths, classes, methods) +- Prescribe technical solutions or libraries +- Add architectural diagrams or code examples +- Specify exact API endpoints or data structures +- Include step-by-step implementation instructions +- Add "how to build" guidance diff --git a/.cursor/skills/decompose/templates/initial-structure.md b/.cursor/skills/decompose/templates/initial-structure.md new file mode 100644 index 0000000..92f124b --- /dev/null +++ b/.cursor/skills/decompose/templates/initial-structure.md @@ -0,0 +1,113 @@ +# Initial Structure Plan Template + +Use this template for the bootstrap structure plan. Save as `TASKS_DIR//initial_structure.md`. + +--- + +```markdown +# Initial Project Structure Plan + +**Date**: [YYYY-MM-DD] +**Tech Stack**: [language, framework, database, etc.] +**Source**: architecture.md, component specs from _docs/02_plans// + +## Project Folder Layout + +``` +project-root/ +├── [folder structure based on tech stack and components] +└── ... +``` + +### Layout Rationale + +[Brief explanation of why this structure was chosen — language conventions, framework patterns, etc.] + +## DTOs and Interfaces + +### Shared DTOs + +| DTO Name | Used By Components | Fields Summary | +|----------|-------------------|---------------| +| [name] | [component list] | [key fields] | + +### Component Interfaces + +| Component | Interface | Methods | Exposed To | +|-----------|-----------|---------|-----------| +| [##]_[name] | [InterfaceName] | [method list] | [consumers] | + +## CI/CD Pipeline + +| Stage | Purpose | Trigger | +|-------|---------|---------| +| Build | Compile/bundle the application | Every push | +| Lint / Static Analysis | Code quality and style checks | Every push | +| Unit Tests | Run unit test suite | Every push | +| Integration Tests | Run integration test suite | Every push | +| Security Scan | SAST / dependency check | Every push | +| Deploy to Staging | Deploy to staging environment | Merge to staging branch | + +### Pipeline Configuration Notes + +[Framework-specific notes: CI tool, runners, caching, parallelism, etc.] + +## Environment Strategy + +| Environment | Purpose | Configuration Notes | +|-------------|---------|-------------------| +| Development | Local development | [local DB, mock services, debug flags] | +| Staging | Pre-production testing | [staging DB, staging services, production-like config] | +| Production | Live system | [production DB, real services, optimized config] | + +### Environment Variables + +| Variable | Dev | Staging | Production | Description | +|----------|-----|---------|------------|-------------| +| [VAR_NAME] | [value/source] | [value/source] | [value/source] | [purpose] | + +## Database Migration Approach + +**Migration tool**: [tool name] +**Strategy**: [migration strategy — e.g., versioned scripts, ORM migrations] + +### Initial Schema + +[Key tables/collections that need to be created, referencing component data access patterns] + +## Test Structure + +``` +tests/ +├── unit/ +│ ├── [component_1]/ +│ ├── [component_2]/ +│ └── ... +├── integration/ +│ ├── test_data/ +│ └── [test files] +└── ... +``` + +### Test Configuration Notes + +[Test runner, fixtures, test data management, isolation strategy] + +## Implementation Order + +| Order | Component | Reason | +|-------|-----------|--------| +| 1 | [##]_[name] | [why first — foundational, no dependencies] | +| 2 | [##]_[name] | [depends on #1] | +| ... | ... | ... | +``` + +--- + +## Guidance Notes + +- This is a PLAN document, not code. The `3.05_implement_initial_structure` command executes it. +- Focus on structure and organization decisions, not implementation details. +- Reference component specs for interface and DTO details — don't repeat everything. +- The folder layout should follow conventions of the identified tech stack. +- Environment strategy should account for secrets management and configuration. diff --git a/.cursor/skills/decompose/templates/summary.md b/.cursor/skills/decompose/templates/summary.md new file mode 100644 index 0000000..9241e74 --- /dev/null +++ b/.cursor/skills/decompose/templates/summary.md @@ -0,0 +1,59 @@ +# Decomposition Summary Template + +Use this template after all steps complete. Save as `TASKS_DIR//SUMMARY.md`. + +--- + +```markdown +# Decomposition Summary + +**Date**: [YYYY-MM-DD] +**Topic**: [topic name] +**Total Components**: [N] +**Total Features**: [N] +**Total Complexity Points**: [N] + +## Component Breakdown + +| # | Component | Features | Total Points | Jira Epic | +|---|-----------|----------|-------------|-----------| +| 01 | [name] | [count] | [sum] | [EPIC-ID] | +| 02 | [name] | [count] | [sum] | [EPIC-ID] | +| ... | ... | ... | ... | ... | + +## Feature List + +| Component | Feature | Complexity | Jira Task | Dependencies | +|-----------|---------|-----------|-----------|-------------| +| [##]_[name] | [##].[##]_feature_[name] | [points] | [TASK-ID] | [deps or "None"] | +| ... | ... | ... | ... | ... | + +## Implementation Order + +Recommended sequence based on dependency analysis: + +| Phase | Components / Features | Rationale | +|-------|----------------------|-----------| +| 1 | [list] | [foundational, no dependencies] | +| 2 | [list] | [depends on phase 1] | +| 3 | [list] | [depends on phase 1-2] | +| ... | ... | ... | + +### Parallelization Opportunities + +[Features/components that can be implemented concurrently within each phase] + +## Cross-Component Dependencies + +| From (Feature) | To (Feature) | Dependency Type | +|----------------|-------------|-----------------| +| [comp.feature] | [comp.feature] | [data / API / event] | +| ... | ... | ... | + +## Artifacts Produced + +- `initial_structure.md` — project skeleton plan +- `cross_dependencies.md` — dependency matrix +- `[##]_[name]/[##].[##]_feature_*.md` — feature specs per component +- Jira tasks created under respective epics +``` diff --git a/.cursor/skills/plan/SKILL.md b/.cursor/skills/plan/SKILL.md new file mode 100644 index 0000000..36cea21 --- /dev/null +++ b/.cursor/skills/plan/SKILL.md @@ -0,0 +1,393 @@ +--- +name: plan +description: | + Decompose a solution into architecture, system flows, components, tests, and Jira epics. + Systematic 5-step planning workflow with BLOCKING gates, self-verification, and structured artifact management. + Supports project mode (_docs/ + _docs/02_plans/ structure) and standalone mode (@file.md). + Trigger phrases: + - "plan", "decompose solution", "architecture planning" + - "break down the solution", "create planning documents" + - "component decomposition", "solution analysis" +disable-model-invocation: true +--- + +# Solution Planning + +Decompose a problem and solution into architecture, system flows, components, tests, and Jira epics through a systematic 5-step workflow. + +## Core Principles + +- **Single Responsibility**: each component does one thing well; do not spread related logic across components +- **Dumb code, smart data**: keep logic simple, push complexity into data structures and configuration +- **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work +- **Ask, don't assume**: when requirements are ambiguous, ask the user before proceeding +- **Plan, don't code**: this workflow produces documents and specs, never implementation code + +## Context Resolution + +Determine the operating mode based on invocation before any other logic runs. + +**Project mode** (no explicit input file provided): +- PROBLEM_FILE: `_docs/00_problem/problem.md` +- SOLUTION_FILE: `_docs/01_solution/solution.md` +- PLANS_DIR: `_docs/02_plans/` +- All existing guardrails apply as-is. + +**Standalone mode** (explicit input file provided, e.g. `/plan @some_doc.md`): +- INPUT_FILE: the provided file (treated as combined problem + solution context) +- Derive `` from the input filename (without extension) +- PLANS_DIR: `_standalone//plans/` +- Guardrails relaxed: only INPUT_FILE must exist and be non-empty +- `acceptance_criteria.md` and `restrictions.md` are optional — warn if absent + +Announce the detected mode and resolved paths to the user before proceeding. + +## Input Specification + +### Required Files + +**Project mode:** + +| File | Purpose | +|------|---------| +| PROBLEM_FILE (`_docs/00_problem/problem.md`) | Problem description and context | +| `_docs/00_problem/input_data/` | Reference data examples (if available) | +| `_docs/00_problem/restrictions.md` | Constraints and limitations (if available) | +| `_docs/00_problem/acceptance_criteria.md` | Measurable acceptance criteria (if available) | +| SOLUTION_FILE (`_docs/01_solution/solution.md`) | Solution draft to decompose | + +**Standalone mode:** + +| File | Purpose | +|------|---------| +| INPUT_FILE (the provided file) | Combined problem + solution context | + +### Prerequisite Checks (BLOCKING) + +**Project mode:** +1. PROBLEM_FILE exists and is non-empty — **STOP if missing** +2. SOLUTION_FILE exists and is non-empty — **STOP if missing** +3. Create PLANS_DIR if it does not exist +4. If `PLANS_DIR//` already exists, ask user: **resume from last checkpoint or start fresh?** + +**Standalone mode:** +1. INPUT_FILE exists and is non-empty — **STOP if missing** +2. Warn if no `restrictions.md` or `acceptance_criteria.md` provided alongside INPUT_FILE +3. Create PLANS_DIR if it does not exist +4. If `PLANS_DIR//` already exists, ask user: **resume from last checkpoint or start fresh?** + +## Artifact Management + +### Directory Structure + +At the start of planning, create a topic-named working directory under PLANS_DIR: + +``` +PLANS_DIR// +├── architecture.md +├── system-flows.md +├── risk_mitigations.md +├── risk_mitigations_02.md (iterative, ## as sequence) +├── components/ +│ ├── 01_[name]/ +│ │ ├── description.md +│ │ └── tests.md +│ ├── 02_[name]/ +│ │ ├── description.md +│ │ └── tests.md +│ └── ... +├── common-helpers/ +│ ├── 01_helper_[name]/ +│ ├── 02_helper_[name]/ +│ └── ... +├── e2e_test_infrastructure.md +├── diagrams/ +│ ├── components.drawio +│ └── flows/ +│ ├── flow_[name].md (Mermaid) +│ └── ... +└── FINAL_report.md +``` + +### Save Timing + +| Step | Save immediately after | Filename | +|------|------------------------|----------| +| Step 1 | Architecture analysis complete | `architecture.md` | +| Step 1 | System flows documented | `system-flows.md` | +| Step 2 | Each component analyzed | `components/[##]_[name]/description.md` | +| Step 2 | Common helpers generated | `common-helpers/[##]_helper_[name].md` | +| Step 2 | Diagrams generated | `diagrams/` | +| Step 3 | Risk assessment complete | `risk_mitigations.md` | +| Step 4 | Tests written per component | `components/[##]_[name]/tests.md` | +| Step 4b | E2E test infrastructure spec | `e2e_test_infrastructure.md` | +| Step 5 | Epics created in Jira | Jira via MCP | +| Final | All steps complete | `FINAL_report.md` | + +### Save Principles + +1. **Save immediately**: write to disk as soon as a step completes; do not wait until the end +2. **Incremental updates**: same file can be updated multiple times; append or replace +3. **Preserve process**: keep all intermediate files even after integration into final report +4. **Enable recovery**: if interrupted, resume from the last saved artifact (see Resumability) + +### Resumability + +If `PLANS_DIR//` already contains artifacts: + +1. List existing files and match them to the save timing table above +2. Identify the last completed step based on which artifacts exist +3. Resume from the next incomplete step +4. Inform the user which steps are being skipped + +## Progress Tracking + +At the start of execution, create a TodoWrite with all steps (1 through 5, including 4b). Update status as each step completes. + +## Workflow + +### Step 1: Solution Analysis + +**Role**: Professional software architect +**Goal**: Produce `architecture.md` and `system-flows.md` from the solution draft +**Constraints**: No code, no component-level detail yet; focus on system-level view + +1. Read all input files thoroughly +2. Research unknown or questionable topics via internet; ask user about ambiguities +3. Document architecture using `templates/architecture.md` as structure +4. Document system flows using `templates/system-flows.md` as structure + +**Self-verification**: +- [ ] Architecture covers all capabilities mentioned in solution.md +- [ ] System flows cover all main user/system interactions +- [ ] No contradictions with problem.md or restrictions.md +- [ ] Technology choices are justified + +**Save action**: Write `architecture.md` and `system-flows.md` + +**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms. + +--- + +### Step 2: Component Decomposition + +**Role**: Professional software architect +**Goal**: Decompose the architecture into components with detailed specs +**Constraints**: No code; only names, interfaces, inputs/outputs. Follow SRP strictly. + +1. Identify components from the architecture; think about separation, reusability, and communication patterns +2. If additional components are needed (data preparation, shared helpers), create them +3. For each component, write a spec using `templates/component-spec.md` as structure +4. Generate diagrams: + - draw.io component diagram showing relations (minimize line intersections, group semantically coherent components, place external users near their components) + - Mermaid flowchart per main control flow +5. Components can share and reuse common logic, same for multiple components. Hence for such occurences common-helpers folder is specified. + +**Self-verification**: +- [ ] Each component has a single, clear responsibility +- [ ] No functionality is spread across multiple components +- [ ] All inter-component interfaces are defined (who calls whom, with what) +- [ ] Component dependency graph has no circular dependencies +- [ ] All components from architecture.md are accounted for + +**Save action**: Write: + - each component `components/[##]_[name]/description.md` + - comomon helper `common-helpers/[##]_helper_[name].md` + - diagrams `diagrams/` + +**BLOCKING**: Present component list with one-line summaries to user. Do NOT proceed until user confirms. + +--- + +### Step 3: Architecture Review & Risk Assessment + +**Role**: Professional software architect and analyst +**Goal**: Validate all artifacts for consistency, then identify and mitigate risks +**Constraints**: This is a review step — fix problems found, do not add new features + +#### 3a. Evaluator Pass (re-read ALL artifacts) + +Review checklist: +- [ ] All components follow Single Responsibility Principle +- [ ] All components follow dumb code / smart data principle +- [ ] Inter-component interfaces are consistent (caller's output matches callee's input) +- [ ] No circular dependencies in the dependency graph +- [ ] No missing interactions between components +- [ ] No over-engineering — is there a simpler decomposition? +- [ ] Security considerations addressed in component design +- [ ] Performance bottlenecks identified +- [ ] API contracts are consistent across components + +Fix any issues found before proceeding to risk identification. + +#### 3b. Risk Identification + +1. Identify technical and project risks +2. Assess probability and impact using `templates/risk-register.md` +3. Define mitigation strategies +4. Apply mitigations to architecture, flows, and component documents where applicable + +**Self-verification**: +- [ ] Every High/Critical risk has a concrete mitigation strategy +- [ ] Mitigations are reflected in the relevant component or architecture docs +- [ ] No new risks introduced by the mitigations themselves + +**Save action**: Write `risk_mitigations.md` + +**BLOCKING**: Present risk summary to user. Ask whether assessment is sufficient. + +**Iterative**: If user requests another round, repeat Step 3 and write `risk_mitigations_##.md` (## as sequence number). Continue until user confirms. + +--- + +### Step 4: Test Specifications + +**Role**: Professional Quality Assurance Engineer +**Goal**: Write test specs for each component achieving minimum 75% acceptance criteria coverage +**Constraints**: Test specs only — no test code. Each test must trace to an acceptance criterion. + +1. For each component, write tests using `templates/test-spec.md` as structure +2. Cover all 4 types: integration, performance, security, acceptance +3. Include test data management (setup, teardown, isolation) +4. Verify traceability: every acceptance criterion from `acceptance_criteria.md` must be covered by at least one test + +**Self-verification**: +- [ ] Every acceptance criterion has at least one test covering it +- [ ] Test inputs are realistic and well-defined +- [ ] Expected results are specific and measurable +- [ ] No component is left without tests + +**Save action**: Write each `components/[##]_[name]/tests.md` + +--- + +### Step 4b: E2E Black-Box Test Infrastructure + +**Role**: Professional Quality Assurance Engineer +**Goal**: Specify a separate consumer application and Docker environment for black-box end-to-end testing of the main system +**Constraints**: Spec only — no test code. Consumer must treat the main system as a black box (no internal imports, no direct DB access). + +1. Define Docker environment: services (system under test, test DB, consumer app, dependencies), networks, volumes +2. Specify consumer application: tech stack, entry point, communication interfaces with the main system +3. Define E2E test scenarios from acceptance criteria — focus on critical end-to-end use cases that cross component boundaries +4. Specify test data management: seed data, isolation strategy, external dependency mocks +5. Define CI/CD integration: when to run, gate behavior, timeout +6. Define reporting format (CSV: test ID, name, execution time, result, error message) + +Use `templates/e2e-test-infrastructure.md` as structure. + +**Self-verification**: +- [ ] Critical acceptance criteria are covered by at least one E2E scenario +- [ ] Consumer app has no direct access to system internals +- [ ] Docker environment is self-contained (`docker compose up` sufficient) +- [ ] External dependencies have mock/stub services defined + +**Save action**: Write `e2e_test_infrastructure.md` + +--- + +### Step 5: Jira Epics + +**Role**: Professional product manager +**Goal**: Create Jira epics from components, ordered by dependency +**Constraints**: Be concise — fewer words with the same meaning is better + +1. Generate Jira Epics from components using Jira MCP, structured per `templates/epic-spec.md` +2. Order epics by dependency (which must be done first) +3. Include effort estimation per epic (T-shirt size or story points range) +4. Ensure each epic has clear acceptance criteria cross-referenced with component specs +5. Generate updated draw.io diagram showing component-to-epic mapping + +**Self-verification**: +- [ ] Every component maps to exactly one epic +- [ ] Dependency order is respected (no epic depends on a later one) +- [ ] Acceptance criteria are measurable +- [ ] Effort estimates are realistic + +**Save action**: Epics created in Jira via MCP + +--- + +## Quality Checklist (before FINAL_report.md) + +Before writing the final report, verify ALL of the following: + +### Architecture +- [ ] Covers all capabilities from solution.md +- [ ] Technology choices are justified +- [ ] Deployment model is defined + +### Components +- [ ] Every component follows SRP +- [ ] No circular dependencies +- [ ] All inter-component interfaces are defined and consistent +- [ ] No orphan components (unused by any flow) + +### Risks +- [ ] All High/Critical risks have mitigations +- [ ] Mitigations are reflected in component/architecture docs +- [ ] User has confirmed risk assessment is sufficient + +### Tests +- [ ] Every acceptance criterion is covered by at least one test +- [ ] All 4 test types are represented per component (where applicable) +- [ ] Test data management is defined + +### E2E Test Infrastructure +- [ ] Critical use cases covered by E2E scenarios +- [ ] Docker environment is self-contained +- [ ] Consumer app treats main system as black box +- [ ] CI/CD integration and reporting defined + +### Epics +- [ ] Every component maps to an epic +- [ ] Dependency order is correct +- [ ] Acceptance criteria are measurable + +**Save action**: Write `FINAL_report.md` using `templates/final-report.md` as structure + +## Common Mistakes + +- **Coding during planning**: this workflow produces documents, never code +- **Multi-responsibility components**: if a component does two things, split it +- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation +- **Diagrams without data**: generate diagrams only after the underlying structure is documented +- **Copy-pasting problem.md**: the architecture doc should analyze and transform, not repeat the input +- **Vague interfaces**: "component A talks to component B" is not enough; define the method, input, output +- **Ignoring restrictions.md**: every constraint must be traceable in the architecture or risk register + +## Escalation Rules + +| Situation | Action | +|-----------|--------| +| Ambiguous requirements | ASK user | +| Missing acceptance criteria | ASK user | +| Technology choice with multiple valid options | ASK user | +| Component naming | PROCEED, confirm at next BLOCKING gate | +| File structure within templates | PROCEED | +| Contradictions between input files | ASK user | +| Risk mitigation requires architecture change | ASK user | + +## Methodology Quick Reference + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Solution Planning (5-Step Method) │ +├────────────────────────────────────────────────────────────────┤ +│ CONTEXT: Resolve mode (project vs standalone) + set paths │ +│ 1. Solution Analysis → architecture.md, system-flows.md │ +│ [BLOCKING: user confirms architecture] │ +│ 2. Component Decompose → components/[##]_[name]/description │ +│ [BLOCKING: user confirms decomposition] │ +│ 3. Review & Risk Assess → risk_mitigations.md │ +│ [BLOCKING: user confirms risks, iterative] │ +│ 4. Test Specifications → components/[##]_[name]/tests.md │ +│ 4b.E2E Test Infra → e2e_test_infrastructure.md │ +│ 5. Jira Epics → Jira via MCP │ +│ ───────────────────────────────────────────────── │ +│ Quality Checklist → FINAL_report.md │ +├────────────────────────────────────────────────────────────────┤ +│ Principles: SRP · Dumb code/smart data · Save immediately │ +│ Ask don't assume · Plan don't code │ +└────────────────────────────────────────────────────────────────┘ +``` diff --git a/.cursor/skills/plan/templates/architecture.md b/.cursor/skills/plan/templates/architecture.md new file mode 100644 index 0000000..0f05dc0 --- /dev/null +++ b/.cursor/skills/plan/templates/architecture.md @@ -0,0 +1,128 @@ +# Architecture Document Template + +Use this template for the architecture document. Save as `_docs/02_plans//architecture.md`. + +--- + +```markdown +# [System Name] — Architecture + +## 1. System Context + +**Problem being solved**: [One paragraph summarizing the problem from problem.md] + +**System boundaries**: [What is inside the system vs. external] + +**External systems**: + +| System | Integration Type | Direction | Purpose | +|--------|-----------------|-----------|---------| +| [name] | REST / Queue / DB / File | Inbound / Outbound / Both | [why] | + +## 2. Technology Stack + +| Layer | Technology | Version | Rationale | +|-------|-----------|---------|-----------| +| Language | | | | +| Framework | | | | +| Database | | | | +| Cache | | | | +| Message Queue | | | | +| Hosting | | | | +| CI/CD | | | | + +**Key constraints from restrictions.md**: +- [Constraint 1 and how it affects technology choices] +- [Constraint 2] + +## 3. Deployment Model + +**Environments**: Development, Staging, Production + +**Infrastructure**: +- [Cloud provider / On-prem / Hybrid] +- [Container orchestration if applicable] +- [Scaling strategy: horizontal / vertical / auto] + +**Environment-specific configuration**: + +| Config | Development | Production | +|--------|-------------|------------| +| Database | [local/docker] | [managed service] | +| Secrets | [.env file] | [secret manager] | +| Logging | [console] | [centralized] | + +## 4. Data Model Overview + +> High-level data model covering the entire system. Detailed per-component models go in component specs. + +**Core entities**: + +| Entity | Description | Owned By Component | +|--------|-------------|--------------------| +| [entity] | [what it represents] | [component ##] | + +**Key relationships**: +- [Entity A] → [Entity B]: [relationship description] + +**Data flow summary**: +- [Source] → [Transform] → [Destination]: [what data and why] + +## 5. Integration Points + +### Internal Communication + +| From | To | Protocol | Pattern | Notes | +|------|----|----------|---------|-------| +| [component] | [component] | Sync REST / Async Queue / Direct call | Request-Response / Event / Command | | + +### External Integrations + +| External System | Protocol | Auth | Rate Limits | Failure Mode | +|----------------|----------|------|-------------|--------------| +| [system] | [REST/gRPC/etc] | [API key/OAuth/etc] | [limits] | [retry/circuit breaker/fallback] | + +## 6. Non-Functional Requirements + +| Requirement | Target | Measurement | Priority | +|------------|--------|-------------|----------| +| Availability | [e.g., 99.9%] | [how measured] | High/Medium/Low | +| Latency (p95) | [e.g., <200ms] | [endpoint/operation] | | +| Throughput | [e.g., 1000 req/s] | [peak/sustained] | | +| Data retention | [e.g., 90 days] | [which data] | | +| Recovery (RPO/RTO) | [e.g., RPO 1hr, RTO 4hr] | | | +| Scalability | [e.g., 10x current load] | [timeline] | | + +## 7. Security Architecture + +**Authentication**: [mechanism — JWT / session / API key] + +**Authorization**: [RBAC / ABAC / per-resource] + +**Data protection**: +- At rest: [encryption method] +- In transit: [TLS version] +- Secrets management: [tool/approach] + +**Audit logging**: [what is logged, where, retention] + +## 8. Key Architectural Decisions + +Record significant decisions that shaped the architecture. + +### ADR-001: [Decision Title] + +**Context**: [Why this decision was needed] + +**Decision**: [What was decided] + +**Alternatives considered**: +1. [Alternative 1] — rejected because [reason] +2. [Alternative 2] — rejected because [reason] + +**Consequences**: [Trade-offs accepted] + +### ADR-002: [Decision Title] + +... +``` diff --git a/.cursor/skills/plan/templates/component-spec.md b/.cursor/skills/plan/templates/component-spec.md new file mode 100644 index 0000000..d016997 --- /dev/null +++ b/.cursor/skills/plan/templates/component-spec.md @@ -0,0 +1,156 @@ +# Component Specification Template + +Use this template for each component. Save as `components/[##]_[name]/description.md`. + +--- + +```markdown +# [Component Name] + +## 1. High-Level Overview + +**Purpose**: [One sentence: what this component does and its role in the system] + +**Architectural Pattern**: [e.g., Repository, Event-driven, Pipeline, Facade, etc.] + +**Upstream dependencies**: [Components that this component calls or consumes from] + +**Downstream consumers**: [Components that call or consume from this component] + +## 2. Internal Interfaces + +For each interface this component exposes internally: + +### Interface: [InterfaceName] + +| Method | Input | Output | Async | Error Types | +|--------|-------|--------|-------|-------------| +| `method_name` | `InputDTO` | `OutputDTO` | Yes/No | `ErrorType1`, `ErrorType2` | + +**Input DTOs**: +``` +[DTO name]: + field_1: type (required/optional) — description + field_2: type (required/optional) — description +``` + +**Output DTOs**: +``` +[DTO name]: + field_1: type — description + field_2: type — description +``` + +## 3. External API Specification + +> Include this section only if the component exposes an external HTTP/gRPC API. +> Skip if the component is internal-only. + +| Endpoint | Method | Auth | Rate Limit | Description | +|----------|--------|------|------------|-------------| +| `/api/v1/...` | GET/POST/PUT/DELETE | Required/Public | X req/min | Brief description | + +**Request/Response schemas**: define per endpoint using OpenAPI-style notation. + +**Example request/response**: +```json +// Request +{ } + +// Response +{ } +``` + +## 4. Data Access Patterns + +### Queries + +| Query | Frequency | Hot Path | Index Needed | +|-------|-----------|----------|--------------| +| [describe query] | High/Medium/Low | Yes/No | Yes/No | + +### Caching Strategy + +| Data | Cache Type | TTL | Invalidation | +|------|-----------|-----|-------------| +| [data item] | In-memory / Redis / None | [duration] | [trigger] | + +### Storage Estimates + +| Table/Collection | Est. Row Count (1yr) | Row Size | Total Size | Growth Rate | +|-----------------|---------------------|----------|------------|-------------| +| [table_name] | | | | /month | + +### Data Management + +**Seed data**: [Required seed data and how to load it] + +**Rollback**: [Rollback procedure for this component's data changes] + +## 5. Implementation Details + +**Algorithmic Complexity**: [Big O for critical methods — only if non-trivial] + +**State Management**: [Local state / Global state / Stateless — explain how state is handled] + +**Key Dependencies**: [External libraries and their purpose] + +| Library | Version | Purpose | +|---------|---------|---------| +| [name] | [version] | [why needed] | + +**Error Handling Strategy**: +- [How errors are caught, propagated, and reported] +- [Retry policy if applicable] +- [Circuit breaker if applicable] + +## 6. Extensions and Helpers + +> List any shared utilities this component needs that should live in a `helpers/` folder. + +| Helper | Purpose | Used By | +|--------|---------|---------| +| [helper_name] | [what it does] | [list of components] | + +## 7. Caveats & Edge Cases + +**Known limitations**: +- [Limitation 1] + +**Potential race conditions**: +- [Race condition scenario, if any] + +**Performance bottlenecks**: +- [Bottleneck description and mitigation approach] + +## 8. Dependency Graph + +**Must be implemented after**: [list of component numbers/names] + +**Can be implemented in parallel with**: [list of component numbers/names] + +**Blocks**: [list of components that depend on this one] + +## 9. Logging Strategy + +| Log Level | When | Example | +|-----------|------|---------| +| ERROR | Unrecoverable failures | `Failed to process order {id}: {error}` | +| WARN | Recoverable issues | `Retry attempt {n} for {operation}` | +| INFO | Key business events | `Order {id} created by user {uid}` | +| DEBUG | Development diagnostics | `Query returned {n} rows in {ms}ms` | + +**Log format**: [structured JSON / plaintext — match system standard] + +**Log storage**: [stdout / file / centralized logging service] +``` + +--- + +## Guidance Notes + +- **Section 3 (External API)**: skip entirely for internal-only components. Include for any component that exposes HTTP endpoints, WebSocket connections, or gRPC services. +- **Section 4 (Storage Estimates)**: critical for components that manage persistent data. Skip for stateless components. +- **Section 5 (Algorithmic Complexity)**: only document if the algorithm is non-trivial (O(n^2) or worse, recursive, etc.). Simple CRUD operations don't need this. +- **Section 6 (Helpers)**: if the helper is used by only one component, keep it inside that component. Only extract to `helpers/` if shared by 2+ components. +- **Section 8 (Dependency Graph)**: this is essential for determining implementation order. Be precise about what "depends on" means — data dependency, API dependency, or shared infrastructure. diff --git a/.cursor/skills/plan/templates/e2e-test-infrastructure.md b/.cursor/skills/plan/templates/e2e-test-infrastructure.md new file mode 100644 index 0000000..0ba96f5 --- /dev/null +++ b/.cursor/skills/plan/templates/e2e-test-infrastructure.md @@ -0,0 +1,141 @@ +# E2E Black-Box Test Infrastructure Template + +Describes a separate consumer application that tests the main system as a black box. +Save as `PLANS_DIR//e2e_test_infrastructure.md`. + +--- + +```markdown +# E2E Test Infrastructure + +## Overview + +**System under test**: [main system name and entry points — API URLs, message queues, etc.] +**Consumer app purpose**: Standalone application that exercises the main system through its public interfaces, validating end-to-end use cases without access to internals. + +## Docker Environment + +### Services + +| Service | Image / Build | Purpose | Ports | +|---------|--------------|---------|-------| +| system-under-test | [main app image or build context] | The main system being tested | [ports] | +| test-db | [postgres/mysql/etc.] | Database for the main system | [ports] | +| e2e-consumer | [build context for consumer app] | Black-box test runner | — | +| [dependency] | [image] | [purpose — cache, queue, etc.] | [ports] | + +### Networks + +| Network | Services | Purpose | +|---------|----------|---------| +| e2e-net | all | Isolated test network | + +### Volumes + +| Volume | Mounted to | Purpose | +|--------|-----------|---------| +| [name] | [service:path] | [test data, DB persistence, etc.] | + +### docker-compose structure + +```yaml +# Outline only — not runnable code +services: + system-under-test: + # main system + test-db: + # database + e2e-consumer: + # consumer test app + depends_on: + - system-under-test +``` + +## Consumer Application + +**Tech stack**: [language, framework, test runner] +**Entry point**: [how it starts — e.g., pytest, jest, custom runner] + +### Communication with system under test + +| Interface | Protocol | Endpoint / Topic | Authentication | +|-----------|----------|-----------------|----------------| +| [API name] | [HTTP/gRPC/AMQP/etc.] | [URL or topic] | [method] | + +### What the consumer does NOT have access to + +- No direct database access to the main system +- No internal module imports +- No shared memory or file system with the main system + +## E2E Test Scenarios + +### Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | E2E Test IDs | Coverage | +|-------|---------------------|-------------|----------| +| AC-01 | [criterion] | E2E-01 | Covered | +| AC-02 | [criterion] | E2E-02, E2E-03 | Covered | +| AC-03 | [criterion] | — | NOT COVERED — [reason] | + +### E2E-01: [Scenario Name] + +**Summary**: [One sentence: what end-to-end use case this validates] + +**Traces to**: AC-01 + +**Preconditions**: +- [System state required before test] + +**Steps**: + +| Step | Consumer Action | Expected System Response | +|------|----------------|------------------------| +| 1 | [call / send] | [response / event] | +| 2 | [call / send] | [response / event] | + +**Max execution time**: [e.g., 10s] + +--- + +### E2E-02: [Scenario Name] + +(repeat structure) + +--- + +## Test Data Management + +**Seed data**: + +| Data Set | Description | How Loaded | Cleanup | +|----------|-------------|-----------|---------| +| [name] | [what it contains] | [SQL script / API call / fixture file] | [how removed after test] | + +**Isolation strategy**: [e.g., each test run gets a fresh DB via container restart, or transactions are rolled back, or namespaced data] + +**External dependencies**: [any external APIs that need mocking or sandbox environments] + +## CI/CD Integration + +**When to run**: [e.g., on PR merge to dev, nightly, before production deploy] +**Pipeline stage**: [where in the CI pipeline this fits] +**Gate behavior**: [block merge / warning only / manual approval] +**Timeout**: [max total suite duration before considered failed] + +## Reporting + +**Format**: CSV +**Columns**: Test ID, Test Name, Execution Time (ms), Result (PASS/FAIL/SKIP), Error Message (if FAIL) +**Output path**: [where the CSV is written — e.g., ./e2e-results/report.csv] +``` + +--- + +## Guidance Notes + +- Every E2E test MUST trace to at least one acceptance criterion. If it doesn't, question whether it's needed. +- The consumer app must treat the main system as a true black box — no internal imports, no direct DB queries against the main system's database. +- Keep the number of E2E tests focused on critical use cases. Exhaustive testing belongs in per-component tests (Step 4). +- Docker environment should be self-contained — `docker compose up` must be sufficient to run the full suite. +- If the main system requires external services (payment gateways, third-party APIs), define mock/stub services in the Docker environment. diff --git a/.cursor/skills/plan/templates/epic-spec.md b/.cursor/skills/plan/templates/epic-spec.md new file mode 100644 index 0000000..26bb953 --- /dev/null +++ b/.cursor/skills/plan/templates/epic-spec.md @@ -0,0 +1,127 @@ +# Jira Epic Template + +Use this template for each Jira epic. Create epics via Jira MCP. + +--- + +```markdown +## Epic: [Component Name] — [Outcome] + +**Example**: Data Ingestion — Near-real-time pipeline + +### Epic Summary + +[1-2 sentences: what we are building + why it matters] + +### Problem / Context + +[Current state, pain points, constraints, business opportunities. +Link to architecture.md and relevant component spec.] + +### Scope + +**In Scope**: +- [Capability 1 — describe what, not how] +- [Capability 2] +- [Capability 3] + +**Out of Scope**: +- [Explicit exclusion 1 — prevents scope creep] +- [Explicit exclusion 2] + +### Assumptions + +- [System design assumption] +- [Data structure assumption] +- [Infrastructure assumption] + +### Dependencies + +**Epic dependencies** (must be completed first): +- [Epic name / ID] + +**External dependencies**: +- [Services, hardware, environments, certificates, data sources] + +### Effort Estimation + +**T-shirt size**: S / M / L / XL +**Story points range**: [min]-[max] + +### Users / Consumers + +| Type | Who | Key Use Cases | +|------|-----|--------------| +| Internal | [team/role] | [use case] | +| External | [user type] | [use case] | +| System | [service name] | [integration point] | + +### Requirements + +**Functional**: +- [API expectations, events, data handling] +- [Idempotency, retry behavior] + +**Non-functional**: +- [Availability, latency, throughput targets] +- [Scalability, processing limits, data retention] + +**Security / Compliance**: +- [Authentication, encryption, secrets management] +- [Logging, audit trail] +- [SOC2 / ISO / GDPR if applicable] + +### Design & Architecture + +- Architecture doc: `_docs/02_plans//architecture.md` +- Component spec: `_docs/02_plans//components/[##]_[name]/description.md` +- System flows: `_docs/02_plans//system-flows.md` + +### Definition of Done + +- [ ] All in-scope capabilities implemented +- [ ] Automated tests pass (unit + integration + e2e) +- [ ] Minimum coverage threshold met (75%) +- [ ] Runbooks written (if applicable) +- [ ] Documentation updated + +### Acceptance Criteria + +| # | Criterion | Measurable Condition | +|---|-----------|---------------------| +| 1 | [criterion] | [how to verify] | +| 2 | [criterion] | [how to verify] | + +### Risks & Mitigations + +| # | Risk | Mitigation | Owner | +|---|------|------------|-------| +| 1 | [top risk] | [mitigation] | [owner] | +| 2 | | | | +| 3 | | | | + +### Labels + +- `component:[name]` +- `env:prod` / `env:stg` +- `type:platform` / `type:data` / `type:integration` + +### Child Issues + +| Type | Title | Points | +|------|-------|--------| +| Spike | [research/investigation task] | [1-3] | +| Task | [implementation task] | [1-5] | +| Task | [implementation task] | [1-5] | +| Enabler | [infrastructure/setup task] | [1-3] | +``` + +--- + +## Guidance Notes + +- Be concise. Fewer words with the same meaning = better epic. +- Capabilities in scope are "what", not "how" — avoid describing implementation details. +- Dependency order matters: epics that must be done first should be listed earlier in the backlog. +- Every epic maps to exactly one component. If a component is too large for one epic, split the component first. +- Complexity points for child issues follow the project standard: 1, 2, 3, 5, 8. Do not create issues above 5 points — split them. diff --git a/.cursor/skills/plan/templates/final-report.md b/.cursor/skills/plan/templates/final-report.md new file mode 100644 index 0000000..b809d65 --- /dev/null +++ b/.cursor/skills/plan/templates/final-report.md @@ -0,0 +1,104 @@ +# Final Planning Report Template + +Use this template after completing all 5 steps and the quality checklist. Save as `_docs/02_plans//FINAL_report.md`. + +--- + +```markdown +# [System Name] — Planning Report + +## Executive Summary + +[2-3 sentences: what was planned, the core architectural approach, and the key outcome (number of components, epics, estimated effort)] + +## Problem Statement + +[Brief restatement from problem.md — transformed, not copy-pasted] + +## Architecture Overview + +[Key architectural decisions and technology stack summary. Reference `architecture.md` for full details.] + +**Technology stack**: [language, framework, database, hosting — one line] + +**Deployment**: [environment strategy — one line] + +## Component Summary + +| # | Component | Purpose | Dependencies | Epic | +|---|-----------|---------|-------------|------| +| 01 | [name] | [one-line purpose] | — | [Jira ID] | +| 02 | [name] | [one-line purpose] | 01 | [Jira ID] | +| ... | | | | | + +**Implementation order** (based on dependency graph): +1. [Phase 1: components that can start immediately] +2. [Phase 2: components that depend on Phase 1] +3. [Phase 3: ...] + +## System Flows + +| Flow | Description | Key Components | +|------|-------------|---------------| +| [name] | [one-line summary] | [component list] | + +[Reference `system-flows.md` for full diagrams and details.] + +## Risk Summary + +| Level | Count | Key Risks | +|-------|-------|-----------| +| Critical | [N] | [brief list] | +| High | [N] | [brief list] | +| Medium | [N] | — | +| Low | [N] | — | + +**Iterations completed**: [N] +**All Critical/High risks mitigated**: Yes / No — [details if No] + +[Reference `risk_mitigations.md` for full register.] + +## Test Coverage + +| Component | Integration | Performance | Security | Acceptance | AC Coverage | +|-----------|-------------|-------------|----------|------------|-------------| +| [name] | [N tests] | [N tests] | [N tests] | [N tests] | [X/Y ACs] | +| ... | | | | | | + +**Overall acceptance criteria coverage**: [X / Y total ACs covered] ([percentage]%) + +## Epic Roadmap + +| Order | Epic | Component | Effort | Dependencies | +|-------|------|-----------|--------|-------------| +| 1 | [Jira ID]: [name] | [component] | [S/M/L/XL] | — | +| 2 | [Jira ID]: [name] | [component] | [S/M/L/XL] | Epic 1 | +| ... | | | | | + +**Total estimated effort**: [sum or range] + +## Key Decisions Made + +| # | Decision | Rationale | Alternatives Rejected | +|---|----------|-----------|----------------------| +| 1 | [decision] | [why] | [what was rejected] | +| 2 | | | | + +## Open Questions + +| # | Question | Impact | Assigned To | +|---|----------|--------|-------------| +| 1 | [unresolved question] | [what it blocks or affects] | [who should answer] | + +## Artifact Index + +| File | Description | +|------|-------------| +| `architecture.md` | System architecture | +| `system-flows.md` | System flows and diagrams | +| `components/01_[name]/description.md` | Component spec | +| `components/01_[name]/tests.md` | Test spec | +| `risk_mitigations.md` | Risk register | +| `diagrams/components.drawio` | Component diagram | +| `diagrams/flows/flow_[name].md` | Flow diagrams | +``` diff --git a/.cursor/skills/plan/templates/risk-register.md b/.cursor/skills/plan/templates/risk-register.md new file mode 100644 index 0000000..71fec69 --- /dev/null +++ b/.cursor/skills/plan/templates/risk-register.md @@ -0,0 +1,99 @@ +# Risk Register Template + +Use this template for risk assessment. Save as `_docs/02_plans//risk_mitigations.md`. +Subsequent iterations: `risk_mitigations_02.md`, `risk_mitigations_03.md`, etc. + +--- + +```markdown +# Risk Assessment — [Topic] — Iteration [##] + +## Risk Scoring Matrix + +| | Low Impact | Medium Impact | High Impact | +|--|------------|---------------|-------------| +| **High Probability** | Medium | High | Critical | +| **Medium Probability** | Low | Medium | High | +| **Low Probability** | Low | Low | Medium | + +## Acceptance Criteria by Risk Level + +| Level | Action Required | +|-------|----------------| +| Low | Accepted, monitored quarterly | +| Medium | Mitigation plan required before implementation | +| High | Mitigation + contingency plan required, reviewed weekly | +| Critical | Must be resolved before proceeding to next planning step | + +## Risk Register + +| ID | Risk | Category | Probability | Impact | Score | Mitigation | Owner | Status | +|----|------|----------|-------------|--------|-------|------------|-------|--------| +| R01 | [risk description] | [category] | High/Med/Low | High/Med/Low | Critical/High/Med/Low | [mitigation strategy] | [owner] | Open/Mitigated/Accepted | +| R02 | | | | | | | | | + +## Risk Categories + +### Technical Risks +- Technology choices may not meet requirements +- Integration complexity underestimated +- Performance targets unachievable +- Security vulnerabilities in design +- Data model cannot support future requirements + +### Schedule Risks +- Dependencies delayed +- Scope creep from ambiguous requirements +- Underestimated complexity + +### Resource Risks +- Key person dependency +- Team lacks experience with chosen technology +- Infrastructure not available in time + +### External Risks +- Third-party API changes or deprecation +- Vendor reliability or pricing changes +- Regulatory or compliance changes +- Data source availability + +## Detailed Risk Analysis + +### R01: [Risk Title] + +**Description**: [Detailed description of the risk] + +**Trigger conditions**: [What would cause this risk to materialize] + +**Affected components**: [List of components impacted] + +**Mitigation strategy**: +1. [Action 1] +2. [Action 2] + +**Contingency plan**: [What to do if mitigation fails] + +**Residual risk after mitigation**: [Low/Medium/High] + +**Documents updated**: [List architecture/component docs that were updated to reflect this mitigation] + +--- + +### R02: [Risk Title] + +(repeat structure above) + +## Architecture/Component Changes Applied + +| Risk ID | Document Modified | Change Description | +|---------|------------------|--------------------| +| R01 | `architecture.md` §3 | [what changed] | +| R01 | `components/02_[name]/description.md` §5 | [what changed] | + +## Summary + +**Total risks identified**: [N] +**Critical**: [N] | **High**: [N] | **Medium**: [N] | **Low**: [N] +**Risks mitigated this iteration**: [N] +**Risks requiring user decision**: [list] +``` diff --git a/.cursor/skills/plan/templates/system-flows.md b/.cursor/skills/plan/templates/system-flows.md new file mode 100644 index 0000000..9b22bf1 --- /dev/null +++ b/.cursor/skills/plan/templates/system-flows.md @@ -0,0 +1,108 @@ +# System Flows Template + +Use this template for the system flows document. Save as `_docs/02_plans//system-flows.md`. +Individual flow diagrams go in `_docs/02_plans//diagrams/flows/flow_[name].md`. + +--- + +```markdown +# [System Name] — System Flows + +## Flow Inventory + +| # | Flow Name | Trigger | Primary Components | Criticality | +|---|-----------|---------|-------------------|-------------| +| F1 | [name] | [user action / scheduled / event] | [component list] | High/Medium/Low | +| F2 | [name] | | | | +| ... | | | | | + +## Flow Dependencies + +| Flow | Depends On | Shares Data With | +|------|-----------|-----------------| +| F1 | — | F2 (via [entity]) | +| F2 | F1 must complete first | F3 | + +--- + +## Flow F1: [Flow Name] + +### Description + +[1-2 sentences: what this flow does, who triggers it, what the outcome is] + +### Preconditions + +- [Condition 1] +- [Condition 2] + +### Sequence Diagram + +```mermaid +sequenceDiagram + participant User + participant ComponentA + participant ComponentB + participant Database + + User->>ComponentA: [action] + ComponentA->>ComponentB: [call with params] + ComponentB->>Database: [query/write] + Database-->>ComponentB: [result] + ComponentB-->>ComponentA: [response] + ComponentA-->>User: [result] +``` + +### Flowchart + +```mermaid +flowchart TD + Start([Trigger]) --> Step1[Step description] + Step1 --> Decision{Condition?} + Decision -->|Yes| Step2[Step description] + Decision -->|No| Step3[Step description] + Step2 --> EndNode([Result]) + Step3 --> EndNode +``` + +### Data Flow + +| Step | From | To | Data | Format | +|------|------|----|------|--------| +| 1 | [source] | [destination] | [what data] | [DTO/event/etc] | +| 2 | | | | | + +### Error Scenarios + +| Error | Where | Detection | Recovery | +|-------|-------|-----------|----------| +| [error type] | [which step] | [how detected] | [what happens] | + +### Performance Expectations + +| Metric | Target | Notes | +|--------|--------|-------| +| End-to-end latency | [target] | [conditions] | +| Throughput | [target] | [peak/sustained] | + +--- + +## Flow F2: [Flow Name] + +(repeat structure above) +``` + +--- + +## Mermaid Diagram Conventions + +Follow these conventions for consistency across all flow diagrams: + +- **Participants**: use component names matching `components/[##]_[name]` +- **Node IDs**: camelCase, no spaces (e.g., `validateInput`, `saveOrder`) +- **Decision nodes**: use `{Question?}` format +- **Start/End**: use `([label])` stadium shape +- **External systems**: use `[[label]]` subroutine shape +- **Subgraphs**: group by component or bounded context +- **No styling**: do not add colors or CSS classes — let the renderer theme handle it +- **Edge labels**: wrap special characters in quotes (e.g., `-->|"O(n) check"|`) diff --git a/.cursor/skills/plan/templates/test-spec.md b/.cursor/skills/plan/templates/test-spec.md new file mode 100644 index 0000000..2b6ee44 --- /dev/null +++ b/.cursor/skills/plan/templates/test-spec.md @@ -0,0 +1,172 @@ +# Test Specification Template + +Use this template for each component's test spec. Save as `components/[##]_[name]/tests.md`. + +--- + +```markdown +# Test Specification — [Component Name] + +## Acceptance Criteria Traceability + +| AC ID | Acceptance Criterion | Test IDs | Coverage | +|-------|---------------------|----------|----------| +| AC-01 | [criterion from acceptance_criteria.md] | IT-01, AT-01 | Covered | +| AC-02 | [criterion] | PT-01 | Covered | +| AC-03 | [criterion] | — | NOT COVERED — [reason] | + +--- + +## Integration Tests + +### IT-01: [Test Name] + +**Summary**: [One sentence: what this test verifies] + +**Traces to**: AC-01, AC-03 + +**Description**: [Detailed test scenario] + +**Input data**: +``` +[specific input data for this test] +``` + +**Expected result**: +``` +[specific expected output or state] +``` + +**Max execution time**: [e.g., 5s] + +**Dependencies**: [other components/services that must be running] + +--- + +### IT-02: [Test Name] + +(repeat structure) + +--- + +## Performance Tests + +### PT-01: [Test Name] + +**Summary**: [One sentence: what performance aspect is tested] + +**Traces to**: AC-02 + +**Load scenario**: +- Concurrent users: [N] +- Request rate: [N req/s] +- Duration: [N minutes] +- Ramp-up: [strategy] + +**Expected results**: + +| Metric | Target | Failure Threshold | +|--------|--------|-------------------| +| Latency (p50) | [target] | [max] | +| Latency (p95) | [target] | [max] | +| Latency (p99) | [target] | [max] | +| Throughput | [target req/s] | [min req/s] | +| Error rate | [target %] | [max %] | + +**Resource limits**: +- CPU: [max %] +- Memory: [max MB/GB] +- Database connections: [max pool size] + +--- + +### PT-02: [Test Name] + +(repeat structure) + +--- + +## Security Tests + +### ST-01: [Test Name] + +**Summary**: [One sentence: what security aspect is tested] + +**Traces to**: AC-04 + +**Attack vector**: [e.g., SQL injection on search endpoint, privilege escalation via direct ID access] + +**Test procedure**: +1. [Step 1] +2. [Step 2] + +**Expected behavior**: [what the system should do — reject, sanitize, log, etc.] + +**Pass criteria**: [specific measurable condition] + +**Fail criteria**: [what constitutes a failure] + +--- + +### ST-02: [Test Name] + +(repeat structure) + +--- + +## Acceptance Tests + +### AT-01: [Test Name] + +**Summary**: [One sentence: what user-facing behavior is verified] + +**Traces to**: AC-01 + +**Preconditions**: +- [Precondition 1] +- [Precondition 2] + +**Steps**: + +| Step | Action | Expected Result | +|------|--------|-----------------| +| 1 | [user action] | [expected outcome] | +| 2 | [user action] | [expected outcome] | +| 3 | [user action] | [expected outcome] | + +--- + +### AT-02: [Test Name] + +(repeat structure) + +--- + +## Test Data Management + +**Required test data**: + +| Data Set | Description | Source | Size | +|----------|-------------|--------|------| +| [name] | [what it contains] | [generated / fixture / copy of prod subset] | [approx size] | + +**Setup procedure**: +1. [How to prepare the test environment] +2. [How to load test data] + +**Teardown procedure**: +1. [How to clean up after tests] +2. [How to restore initial state] + +**Data isolation strategy**: [How tests are isolated from each other — separate DB, transactions, namespacing] +``` + +--- + +## Guidance Notes + +- Every test MUST trace back to at least one acceptance criterion (AC-XX). If a test doesn't trace to any, question whether it's needed. +- If an acceptance criterion has no test covering it, mark it as NOT COVERED and explain why (e.g., "requires manual verification", "deferred to phase 2"). +- Performance test targets should come from the NFR section in `architecture.md`. +- Security tests should cover at minimum: authentication bypass, authorization escalation, injection attacks relevant to this component. +- Not every component needs all 4 test types. A stateless utility component may only need integration tests. diff --git a/.cursor/skills/refactor/SKILL.md b/.cursor/skills/refactor/SKILL.md new file mode 100644 index 0000000..d05c779 --- /dev/null +++ b/.cursor/skills/refactor/SKILL.md @@ -0,0 +1,470 @@ +--- +name: refactor +description: | + Structured refactoring workflow (6-phase method) with three execution modes: + - Full Refactoring: all 6 phases — baseline, discovery, analysis, safety net, execution, hardening + - Targeted Refactoring: skip discovery if docs exist, focus on a specific component/area + - Quick Assessment: phases 0-2 only, outputs a refactoring plan without execution + Supports project mode (_docs/ structure) and standalone mode (@file.md). + Trigger phrases: + - "refactor", "refactoring", "improve code" + - "analyze coupling", "decoupling", "technical debt" + - "refactoring assessment", "code quality improvement" +disable-model-invocation: true +--- + +# Structured Refactoring (6-Phase Method) + +Transform existing codebases through a systematic refactoring workflow: capture baseline, document current state, research improvements, build safety net, execute changes, and harden. + +## Core Principles + +- **Preserve behavior first**: never refactor without a passing test suite +- **Measure before and after**: every change must be justified by metrics +- **Small incremental changes**: commit frequently, never break tests +- **Save immediately**: write artifacts to disk after each phase; never accumulate unsaved work +- **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user + +## Context Resolution + +Determine the operating mode based on invocation before any other logic runs. + +**Project mode** (no explicit input file provided): +- PROBLEM_DIR: `_docs/00_problem/` +- SOLUTION_DIR: `_docs/01_solution/` +- COMPONENTS_DIR: `_docs/02_components/` +- TESTS_DIR: `_docs/02_tests/` +- REFACTOR_DIR: `_docs/04_refactoring/` +- All existing guardrails apply. + +**Standalone mode** (explicit input file provided, e.g. `/refactor @some_component.md`): +- INPUT_FILE: the provided file (treated as component/area description) +- Derive `` from the input filename (without extension) +- REFACTOR_DIR: `_standalone//refactoring/` +- Guardrails relaxed: only INPUT_FILE must exist and be non-empty +- `acceptance_criteria.md` is optional — warn if absent + +Announce the detected mode and resolved paths to the user before proceeding. + +## Mode Detection + +After context resolution, determine the execution mode: + +1. **User explicitly says** "quick assessment" or "just assess" → **Quick Assessment** +2. **User explicitly says** "refactor [component/file/area]" with a specific target → **Targeted Refactoring** +3. **Default** → **Full Refactoring** + +| Mode | Phases Executed | When to Use | +|------|----------------|-------------| +| **Full Refactoring** | 0 → 1 → 2 → 3 → 4 → 5 | Complete refactoring of a system or major area | +| **Targeted Refactoring** | 0 → (skip 1 if docs exist) → 2 → 3 → 4 → 5 | Refactor a specific component; docs already exist | +| **Quick Assessment** | 0 → 1 → 2 | Produce a refactoring roadmap without executing changes | + +Inform the user which mode was detected and confirm before proceeding. + +## Prerequisite Checks (BLOCKING) + +**Project mode:** +1. PROBLEM_DIR exists with `problem.md` (or `problem_description.md`) — **STOP if missing**, ask user to create it +2. If `acceptance_criteria.md` is missing: **warn** and ask whether to proceed +3. Create REFACTOR_DIR if it does not exist +4. If REFACTOR_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?** + +**Standalone mode:** +1. INPUT_FILE exists and is non-empty — **STOP if missing** +2. Warn if no `acceptance_criteria.md` provided +3. Create REFACTOR_DIR if it does not exist + +## Artifact Management + +### Directory Structure + +``` +REFACTOR_DIR/ +├── baseline_metrics.md (Phase 0) +├── discovery/ +│ ├── components/ +│ │ └── [##]_[name].md (Phase 1) +│ ├── solution.md (Phase 1) +│ └── system_flows.md (Phase 1) +├── analysis/ +│ ├── research_findings.md (Phase 2) +│ └── refactoring_roadmap.md (Phase 2) +├── test_specs/ +│ └── [##]_[test_name].md (Phase 3) +├── coupling_analysis.md (Phase 4) +├── execution_log.md (Phase 4) +├── hardening/ +│ ├── technical_debt.md (Phase 5) +│ ├── performance.md (Phase 5) +│ └── security.md (Phase 5) +└── FINAL_report.md (after all phases) +``` + +### Save Timing + +| Phase | Save immediately after | Filename | +|-------|------------------------|----------| +| Phase 0 | Baseline captured | `baseline_metrics.md` | +| Phase 1 | Each component documented | `discovery/components/[##]_[name].md` | +| Phase 1 | Solution synthesized | `discovery/solution.md`, `discovery/system_flows.md` | +| Phase 2 | Research complete | `analysis/research_findings.md` | +| Phase 2 | Roadmap produced | `analysis/refactoring_roadmap.md` | +| Phase 3 | Test specs written | `test_specs/[##]_[test_name].md` | +| Phase 4 | Coupling analyzed | `coupling_analysis.md` | +| Phase 4 | Execution complete | `execution_log.md` | +| Phase 5 | Each hardening track | `hardening/.md` | +| Final | All phases done | `FINAL_report.md` | + +### Resumability + +If REFACTOR_DIR already contains artifacts: + +1. List existing files and match to the save timing table +2. Identify the last completed phase based on which artifacts exist +3. Resume from the next incomplete phase +4. Inform the user which phases are being skipped + +## Progress Tracking + +At the start of execution, create a TodoWrite with all applicable phases. Update status as each phase completes. + +## Workflow + +### Phase 0: Context & Baseline + +**Role**: Software engineer preparing for refactoring +**Goal**: Collect refactoring goals and capture baseline metrics +**Constraints**: Measurement only — no code changes + +#### 0a. Collect Goals + +If PROBLEM_DIR files do not yet exist, help the user create them: + +1. `problem.md` — what the system currently does, what changes are needed, pain points +2. `acceptance_criteria.md` — success criteria for the refactoring +3. `security_approach.md` — security requirements (if applicable) + +Store in PROBLEM_DIR. + +#### 0b. Capture Baseline + +1. Read problem description and acceptance criteria +2. Measure current system metrics using project-appropriate tools: + +| Metric Category | What to Capture | +|----------------|-----------------| +| **Coverage** | Overall, unit, integration, critical paths | +| **Complexity** | Cyclomatic complexity (avg + top 5 functions), LOC, tech debt ratio | +| **Code Smells** | Total, critical, major | +| **Performance** | Response times (P50/P95/P99), CPU/memory, throughput | +| **Dependencies** | Total count, outdated, security vulnerabilities | +| **Build** | Build time, test execution time, deployment time | + +3. Create functionality inventory: all features/endpoints with status and coverage + +**Self-verification**: +- [ ] All metric categories measured (or noted as N/A with reason) +- [ ] Functionality inventory is complete +- [ ] Measurements are reproducible + +**Save action**: Write `REFACTOR_DIR/baseline_metrics.md` + +**BLOCKING**: Present baseline summary to user. Do NOT proceed until user confirms. + +--- + +### Phase 1: Discovery + +**Role**: Principal software architect +**Goal**: Generate documentation from existing code and form solution description +**Constraints**: Document what exists, not what should be. No code changes. + +**Skip condition** (Targeted mode): If `COMPONENTS_DIR` and `SOLUTION_DIR` already contain documentation for the target area, skip to Phase 2. Ask user to confirm skip. + +#### 1a. Document Components + +For each component in the codebase: + +1. Analyze project structure, directories, files +2. Go file by file, analyze each method +3. Analyze connections between components + +Write per component to `REFACTOR_DIR/discovery/components/[##]_[name].md`: +- Purpose and architectural patterns +- Mermaid diagrams for logic flows +- API reference table (name, description, input, output) +- Implementation details: algorithmic complexity, state management, dependencies +- Caveats, edge cases, known limitations + +#### 1b. Synthesize Solution & Flows + +1. Review all generated component documentation +2. Synthesize into a cohesive solution description +3. Create flow diagrams showing component interactions + +Write: +- `REFACTOR_DIR/discovery/solution.md` — product description, component overview, interaction diagram +- `REFACTOR_DIR/discovery/system_flows.md` — Mermaid flowcharts per major use case + +Also copy to project standard locations if in project mode: +- `SOLUTION_DIR/solution.md` +- `COMPONENTS_DIR/system_flows.md` + +**Self-verification**: +- [ ] Every component in the codebase is documented +- [ ] Solution description covers all components +- [ ] Flow diagrams cover all major use cases +- [ ] Mermaid diagrams are syntactically correct + +**Save action**: Write discovery artifacts + +**BLOCKING**: Present discovery summary to user. Do NOT proceed until user confirms documentation accuracy. + +--- + +### Phase 2: Analysis + +**Role**: Researcher and software architect +**Goal**: Research improvements and produce a refactoring roadmap +**Constraints**: Analysis only — no code changes + +#### 2a. Deep Research + +1. Analyze current implementation patterns +2. Research modern approaches for similar systems +3. Identify what could be done differently +4. Suggest improvements based on state-of-the-art practices + +Write `REFACTOR_DIR/analysis/research_findings.md`: +- Current state analysis: patterns used, strengths, weaknesses +- Alternative approaches per component: current vs alternative, pros/cons, migration effort +- Prioritized recommendations: quick wins + strategic improvements + +#### 2b. Solution Assessment + +1. Assess current implementation against acceptance criteria +2. Identify weak points in codebase, map to specific code areas +3. Perform gap analysis: acceptance criteria vs current state +4. Prioritize changes by impact and effort + +Write `REFACTOR_DIR/analysis/refactoring_roadmap.md`: +- Weak points assessment: location, description, impact, proposed solution +- Gap analysis: what's missing, what needs improvement +- Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements) + +**Self-verification**: +- [ ] All acceptance criteria are addressed in gap analysis +- [ ] Recommendations are grounded in actual code, not abstract +- [ ] Roadmap phases are prioritized by impact +- [ ] Quick wins are identified separately + +**Save action**: Write analysis artifacts + +**BLOCKING**: Present refactoring roadmap to user. Do NOT proceed until user confirms. + +**Quick Assessment mode stops here.** Present final summary and write `FINAL_report.md` with phases 0-2 content. + +--- + +### Phase 3: Safety Net + +**Role**: QA engineer and developer +**Goal**: Design and implement tests that capture current behavior before refactoring +**Constraints**: Tests must all pass on the current codebase before proceeding + +#### 3a. Design Test Specs + +Coverage requirements (must meet before refactoring): +- Minimum overall coverage: 75% +- Critical path coverage: 90% +- All public APIs must have integration tests +- All error handling paths must be tested + +For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_name].md`: +- Integration tests: summary, current behavior, input data, expected result, max expected time +- Acceptance tests: summary, preconditions, steps with expected results +- Coverage analysis: current %, target %, uncovered critical paths + +#### 3b. Implement Tests + +1. Set up test environment and infrastructure if not exists +2. Implement each test from specs +3. Run tests, verify all pass on current codebase +4. Document any discovered issues + +**Self-verification**: +- [ ] Coverage requirements met (75% overall, 90% critical paths) +- [ ] All tests pass on current codebase +- [ ] All public APIs have integration tests +- [ ] Test data fixtures are configured + +**Save action**: Write test specs; implemented tests go into the project's test folder + +**GATE (BLOCKING)**: ALL tests must pass before proceeding to Phase 4. If tests fail, fix the tests (not the code) or ask user for guidance. Do NOT proceed to Phase 4 with failing tests. + +--- + +### Phase 4: Execution + +**Role**: Software architect and developer +**Goal**: Analyze coupling and execute decoupling changes +**Constraints**: Small incremental changes; tests must stay green after every change + +#### 4a. Analyze Coupling + +1. Analyze coupling between components/modules +2. Map dependencies (direct and transitive) +3. Identify circular dependencies +4. Form decoupling strategy + +Write `REFACTOR_DIR/coupling_analysis.md`: +- Dependency graph (Mermaid) +- Coupling metrics per component +- Problem areas: components involved, coupling type, severity, impact +- Decoupling strategy: priority order, proposed interfaces/abstractions, effort estimates + +**BLOCKING**: Present coupling analysis to user. Do NOT proceed until user confirms strategy. + +#### 4b. Execute Decoupling + +For each change in the decoupling strategy: + +1. Implement the change +2. Run integration tests +3. Fix any failures +4. Commit with descriptive message + +Address code smells encountered: long methods, large classes, duplicate code, dead code, magic numbers. + +Write `REFACTOR_DIR/execution_log.md`: +- Change description, files affected, test status per change +- Before/after metrics comparison against baseline + +**Self-verification**: +- [ ] All tests still pass after execution +- [ ] No circular dependencies remain (or reduced per plan) +- [ ] Code smells addressed +- [ ] Metrics improved compared to baseline + +**Save action**: Write execution artifacts + +**BLOCKING**: Present execution summary to user. Do NOT proceed until user confirms. + +--- + +### Phase 5: Hardening (Optional, Parallel Tracks) + +**Role**: Varies per track +**Goal**: Address technical debt, performance, and security +**Constraints**: Each track is optional; user picks which to run + +Present the three tracks and let user choose which to execute: + +#### Track A: Technical Debt + +**Role**: Technical debt analyst + +1. Identify and categorize debt items: design, code, test, documentation +2. Assess each: location, description, impact, effort, interest (cost of not fixing) +3. Prioritize: quick wins → strategic debt → tolerable debt +4. Create actionable plan with prevention measures + +Write `REFACTOR_DIR/hardening/technical_debt.md` + +#### Track B: Performance Optimization + +**Role**: Performance engineer + +1. Profile current performance, identify bottlenecks +2. For each bottleneck: location, symptom, root cause, impact +3. Propose optimizations with expected improvement and risk +4. Implement one at a time, benchmark after each change +5. Verify tests still pass + +Write `REFACTOR_DIR/hardening/performance.md` with before/after benchmarks + +#### Track C: Security Review + +**Role**: Security engineer + +1. Review code against OWASP Top 10 +2. Verify security requirements from `security_approach.md` are met +3. Check: authentication, authorization, input validation, output encoding, encryption, logging + +Write `REFACTOR_DIR/hardening/security.md`: +- Vulnerability assessment: location, type, severity, exploit scenario, fix +- Security controls review +- Compliance check against `security_approach.md` +- Recommendations: critical fixes, improvements, hardening + +**Self-verification** (per track): +- [ ] All findings are grounded in actual code +- [ ] Recommendations are actionable with effort estimates +- [ ] All tests still pass after any changes + +**Save action**: Write hardening artifacts + +--- + +## Final Report + +After all executed phases complete, write `REFACTOR_DIR/FINAL_report.md`: + +- Refactoring mode used and phases executed +- Baseline metrics vs final metrics comparison +- Changes made summary +- Remaining items (deferred to future) +- Lessons learned + +## Escalation Rules + +| Situation | Action | +|-----------|--------| +| Unclear refactoring scope | **ASK user** | +| Ambiguous acceptance criteria | **ASK user** | +| Tests failing before refactoring | **ASK user** — fix tests or fix code? | +| Coupling change risks breaking external contracts | **ASK user** | +| Performance optimization vs readability trade-off | **ASK user** | +| Missing baseline metrics (no test suite, no CI) | **WARN user**, suggest building safety net first | +| Security vulnerability found during refactoring | **WARN user** immediately, don't defer | + +## Trigger Conditions + +When the user wants to: +- Improve existing code structure or quality +- Reduce technical debt or coupling +- Prepare codebase for new features +- Assess code health before major changes + +**Keywords**: "refactor", "refactoring", "improve code", "reduce coupling", "technical debt", "code quality", "decoupling" + +## Methodology Quick Reference + +``` +┌────────────────────────────────────────────────────────────────┐ +│ Structured Refactoring (6-Phase Method) │ +├────────────────────────────────────────────────────────────────┤ +│ CONTEXT: Resolve mode (project vs standalone) + set paths │ +│ MODE: Full / Targeted / Quick Assessment │ +│ │ +│ 0. Context & Baseline → baseline_metrics.md │ +│ [BLOCKING: user confirms baseline] │ +│ 1. Discovery → discovery/ (components, solution) │ +│ [BLOCKING: user confirms documentation] │ +│ 2. Analysis → analysis/ (research, roadmap) │ +│ [BLOCKING: user confirms roadmap] │ +│ ── Quick Assessment stops here ── │ +│ 3. Safety Net → test_specs/ + implemented tests │ +│ [GATE: all tests must pass] │ +│ 4. Execution → coupling_analysis, execution_log │ +│ [BLOCKING: user confirms changes] │ +│ 5. Hardening → hardening/ (debt, perf, security) │ +│ [optional, user picks tracks] │ +│ ───────────────────────────────────────────────── │ +│ FINAL_report.md │ +├────────────────────────────────────────────────────────────────┤ +│ Principles: Preserve behavior · Measure before/after │ +│ Small changes · Save immediately · Ask don't assume│ +└────────────────────────────────────────────────────────────────┘ +``` diff --git a/.cursor/skills/research/SKILL.md b/.cursor/skills/research/SKILL.md new file mode 100644 index 0000000..3ae1aca --- /dev/null +++ b/.cursor/skills/research/SKILL.md @@ -0,0 +1,1091 @@ +--- +name: deep-research +description: | + Deep Research Methodology (8-Step Method) with two execution modes: + - Mode A (Initial Research): Assess acceptance criteria, then research problem and produce solution draft + - Mode B (Solution Assessment): Assess existing solution draft for weak points and produce revised draft + Supports project mode (_docs/ structure) and standalone mode (@file.md). + Auto-detects research mode based on existing solution_draft files. + Trigger phrases: + - "research", "deep research", "deep dive", "in-depth analysis" + - "research this", "investigate", "look into" + - "assess solution", "review solution draft" + - "comparative analysis", "concept comparison", "technical comparison" +--- + +# Deep Research (8-Step Method) + +Transform vague topics raised by users into high-quality, deliverable research reports through a systematic methodology. Operates in two modes: **Initial Research** (produce new solution draft) and **Solution Assessment** (assess and revise existing draft). + +## Core Principles + +- **Conclusions come from mechanism comparison, not "gut feelings"** +- **Pin down the facts first, then reason** +- **Prioritize authoritative sources: L1 > L2 > L3 > L4** +- **Intermediate results must be saved for traceability and reuse** +- **Ask, don't assume** — when any aspect of the problem, criteria, or restrictions is unclear, STOP and ask the user before proceeding + +## Context Resolution + +Determine the operating mode based on invocation before any other logic runs. + +**Project mode** (no explicit input file provided): +- INPUT_DIR: `_docs/00_problem/` +- OUTPUT_DIR: `_docs/01_solution/` +- RESEARCH_DIR: `_docs/00_research/` +- All existing guardrails, mode detection, and draft numbering apply as-is. + +**Standalone mode** (explicit input file provided, e.g. `/research @some_doc.md`): +- INPUT_FILE: the provided file (treated as problem description) +- Derive `` from the input filename (without extension) +- OUTPUT_DIR: `_standalone//01_solution/` +- RESEARCH_DIR: `_standalone//00_research/` +- Guardrails relaxed: only INPUT_FILE must exist and be non-empty +- `restrictions.md` and `acceptance_criteria.md` are optional — warn if absent, proceed if user confirms +- Mode detection uses OUTPUT_DIR for `solution_draft*.md` scanning +- Draft numbering works the same, scoped to OUTPUT_DIR + +Announce the detected mode and resolved paths to the user before proceeding. + +## Project Integration + +### Prerequisite Guardrails (BLOCKING) + +Before any research begins, verify the input context exists. **Do not proceed if guardrails fail.** + +**Project mode:** +1. Check INPUT_DIR exists — **STOP if missing**, ask user to create it and provide problem files +2. Check `problem.md` in INPUT_DIR exists and is non-empty — **STOP if missing** +3. Check for `restrictions.md` and `acceptance_criteria.md` in INPUT_DIR: + - If missing: **warn user** and ask whether to proceed without them or provide them first + - If present: read and validate they are non-empty +4. Read **all** files in INPUT_DIR to ground the investigation in the project context +5. Create OUTPUT_DIR and RESEARCH_DIR if they don't exist + +**Standalone mode:** +1. Check INPUT_FILE exists and is non-empty — **STOP if missing** +2. Warn if no `restrictions.md` or `acceptance_criteria.md` were provided alongside INPUT_FILE — proceed if user confirms +3. Create OUTPUT_DIR and RESEARCH_DIR if they don't exist + +### Mode Detection + +After guardrails pass, determine the execution mode: + +1. Scan OUTPUT_DIR for files matching `solution_draft*.md` +2. **No matches found** → **Mode A: Initial Research** +3. **Matches found** → **Mode B: Solution Assessment** (use the highest-numbered draft as input) +4. **User override**: if the user explicitly says "research from scratch" or "initial research", force Mode A regardless of existing drafts + +Inform the user which mode was detected and confirm before proceeding. + +### Solution Draft Numbering + +All final output is saved as `OUTPUT_DIR/solution_draft##.md` with a 2-digit zero-padded number: + +1. Scan existing files in OUTPUT_DIR matching `solution_draft*.md` +2. Extract the highest existing number +3. Increment by 1 +4. Zero-pad to 2 digits (e.g., `01`, `02`, ..., `10`, `11`) + +Example: if `solution_draft01.md` through `solution_draft10.md` exist, the next output is `solution_draft11.md`. + +### Working Directory & Intermediate Artifact Management + +#### Directory Structure + +At the start of research, **must** create a topic-named working directory under RESEARCH_DIR: + +``` +RESEARCH_DIR// +├── 00_ac_assessment.md # Mode A Phase 1 output: AC & restrictions assessment +├── 00_question_decomposition.md # Step 0-1 output +├── 01_source_registry.md # Step 2 output: all consulted source links +├── 02_fact_cards.md # Step 3 output: extracted facts +├── 03_comparison_framework.md # Step 4 output: selected framework and populated data +├── 04_reasoning_chain.md # Step 6 output: fact → conclusion reasoning +├── 05_validation_log.md # Step 7 output: use-case validation results +└── raw/ # Raw source archive (optional) + ├── source_1.md + └── source_2.md +``` + +### Save Timing & Content + +| Step | Save immediately after completion | Filename | +|------|-----------------------------------|----------| +| Mode A Phase 1 | AC & restrictions assessment tables | `00_ac_assessment.md` | +| Step 0-1 | Question type classification + sub-question list | `00_question_decomposition.md` | +| Step 2 | Each consulted source link, tier, summary | `01_source_registry.md` | +| Step 3 | Each fact card (statement + source + confidence) | `02_fact_cards.md` | +| Step 4 | Selected comparison framework + initial population | `03_comparison_framework.md` | +| Step 6 | Reasoning process for each dimension | `04_reasoning_chain.md` | +| Step 7 | Validation scenarios + results + review checklist | `05_validation_log.md` | +| Step 8 | Complete solution draft | `OUTPUT_DIR/solution_draft##.md` | + +### Save Principles + +1. **Save immediately**: Write to the corresponding file as soon as a step is completed; don't wait until the end +2. **Incremental updates**: Same file can be updated multiple times; append or replace new content +3. **Preserve process**: Keep intermediate files even after their content is integrated into the final report +4. **Enable recovery**: If research is interrupted, progress can be recovered from intermediate files + +## Execution Flow + +### Mode A: Initial Research + +Triggered when no `solution_draft*.md` files exist in OUTPUT_DIR, or when the user explicitly requests initial research. + +#### Phase 1: AC & Restrictions Assessment (BLOCKING) + +**Role**: Professional software architect + +A focused preliminary research pass **before** the main solution research. The goal is to validate that the acceptance criteria and restrictions are realistic before designing a solution around them. + +**Input**: All files from INPUT_DIR (or INPUT_FILE in standalone mode) + +**Task**: +1. Read all problem context files thoroughly +2. **ASK the user about every unclear aspect** — do not assume: + - Unclear problem boundaries → ask + - Ambiguous acceptance criteria values → ask + - Missing context (no `security_approach.md`, no `input_data/`) → ask what they have + - Conflicting restrictions → ask which takes priority +3. Research in internet: + - How realistic are the acceptance criteria for this specific domain? + - How critical is each criterion? + - What domain-specific acceptance criteria are we missing? + - Impact of each criterion value on the whole system quality + - Cost/budget implications of each criterion + - Timeline implications — how long would it take to meet each criterion +4. Research restrictions: + - Are the restrictions realistic? + - Should any be tightened or relaxed? + - Are there additional restrictions we should add? +5. Verify findings with authoritative sources (official docs, papers, benchmarks) + +**Uses Steps 0-3 of the 8-step engine** (question classification, decomposition, source tiering, fact extraction) scoped to AC and restrictions assessment. + +**📁 Save action**: Write `RESEARCH_DIR//00_ac_assessment.md` with format: + +```markdown +# Acceptance Criteria Assessment + +## Acceptance Criteria + +| Criterion | Our Values | Researched Values | Cost/Timeline Impact | Status | +|-----------|-----------|-------------------|---------------------|--------| +| [name] | [current] | [researched range] | [impact] | Added / Modified / Removed | + +## Restrictions Assessment + +| Restriction | Our Values | Researched Values | Cost/Timeline Impact | Status | +|-------------|-----------|-------------------|---------------------|--------| +| [name] | [current] | [researched range] | [impact] | Added / Modified / Removed | + +## Key Findings +[Summary of critical findings] + +## Sources +[Key references used] +``` + +**BLOCKING**: Present the AC assessment tables to the user. Wait for confirmation or adjustments before proceeding to Phase 2. The user may update `acceptance_criteria.md` or `restrictions.md` based on findings. + +--- + +#### Phase 2: Problem Research & Solution Draft + +**Role**: Professional researcher and software architect + +Full 8-step research methodology. Produces the first solution draft. + +**Input**: All files from INPUT_DIR (possibly updated after Phase 1) + Phase 1 artifacts + +**Task** (drives the 8-step engine): +1. Research existing/competitor solutions for similar problems +2. Research the problem thoroughly — all possible ways to solve it, split into components +3. For each component, research all possible solutions and find the most efficient state-of-the-art approaches +4. Verify that suggested tools/libraries actually exist and work as described +5. Include security considerations in each component analysis +6. Provide rough cost estimates for proposed solutions + +Be concise in formulating. The fewer words, the better, but do not miss any important details. + +**📁 Save action**: Write `OUTPUT_DIR/solution_draft##.md` using template: `templates/solution_draft_mode_a.md` + +--- + +#### Phase 3: Tech Stack Consolidation (OPTIONAL) + +**Role**: Software architect evaluating technology choices + +Focused synthesis step — no new 8-step cycle. Uses research already gathered in Phase 2 to make concrete technology decisions. + +**Input**: Latest `solution_draft##.md` from OUTPUT_DIR + all files from INPUT_DIR + +**Task**: +1. Extract technology options from the solution draft's component comparison tables +2. Score each option against: fitness for purpose, maturity, security track record, team expertise, cost, scalability +3. Produce a tech stack summary with selection rationale +4. Assess risks and learning requirements per technology choice + +**📁 Save action**: Write `OUTPUT_DIR/tech_stack.md` with: +- Requirements analysis (functional, non-functional, constraints) +- Technology evaluation tables (language, framework, database, infrastructure, key libraries) with scores +- Tech stack summary block +- Risk assessment and learning requirements tables + +--- + +#### Phase 4: Security Deep Dive (OPTIONAL) + +**Role**: Security architect + +Focused analysis step — deepens the security column from the solution draft into a proper threat model and controls specification. + +**Input**: Latest `solution_draft##.md` from OUTPUT_DIR + `security_approach.md` from INPUT_DIR + problem context + +**Task**: +1. Build threat model: asset inventory, threat actors, attack vectors +2. Define security requirements and proposed controls per component (with risk level) +3. Summarize authentication/authorization, data protection, secure communication, and logging/monitoring approach + +**📁 Save action**: Write `OUTPUT_DIR/security_analysis.md` with: +- Threat model (assets, actors, vectors) +- Per-component security requirements and controls table +- Security controls summary + +--- + +### Mode B: Solution Assessment + +Triggered when `solution_draft*.md` files exist in OUTPUT_DIR. + +**Role**: Professional software architect + +Full 8-step research methodology applied to assessing and improving an existing solution draft. + +**Input**: All files from INPUT_DIR + the latest (highest-numbered) `solution_draft##.md` from OUTPUT_DIR + +**Task** (drives the 8-step engine): +1. Read the existing solution draft thoroughly +2. Research in internet — identify all potential weak points and problems +3. Identify security weak points and vulnerabilities +4. Identify performance bottlenecks +5. Address these problems and find ways to solve them +6. Based on findings, form a new solution draft in the same format +7. During the comparison, try to find the best solution which produces the most quality result within the boundaries of the restrictions. In case of uncertaintis and come closer or above the boundaries, ask the user + +**📁 Save action**: Write `OUTPUT_DIR/solution_draft##.md` (incremented) using template: `templates/solution_draft_mode_b.md` + +**Optional follow-up**: After Mode B completes, the user can request Phase 3 (Tech Stack Consolidation) or Phase 4 (Security Deep Dive) using the revised draft. These phases work identically to their Mode A descriptions above. + +## Escalation Rules + +| Situation | Action | +|-----------|--------| +| Unclear problem boundaries | **ASK user** | +| Ambiguous acceptance criteria values | **ASK user** | +| Missing context files (`security_approach.md`, `input_data/`) | **ASK user** what they have | +| Conflicting restrictions | **ASK user** which takes priority | +| Technology choice with multiple valid options | **ASK user** | +| Contradictions between input files | **ASK user** | +| Missing acceptance criteria or restrictions files | **WARN user**, ask whether to proceed | +| File naming within research artifacts | PROCEED | +| Source tier classification | PROCEED | + +## Trigger Conditions + +When the user wants to: +- Deeply understand a concept/technology/phenomenon +- Compare similarities and differences between two or more things +- Gather information and evidence for a decision +- Assess or improve an existing solution draft + +**Keywords**: +- "deep research", "deep dive", "in-depth analysis" +- "research this", "investigate", "look into" +- "assess solution", "review draft", "improve solution" +- "comparative analysis", "concept comparison", "technical comparison" + +**Differentiation from other Skills**: +- Needs a **visual knowledge graph** → use `research-to-diagram` +- Needs **written output** (articles/tutorials) → use `wsy-writer` +- Needs **material organization** → use `material-to-markdown` +- Needs **research + solution draft** → use this Skill + +## Research Engine (8-Step Method) + +The 8-step method is the core research engine used by both modes. Steps 0-1 and Step 8 have mode-specific behavior; Steps 2-7 are identical regardless of mode. + +### Step 0: Question Type Classification + +First, classify the research question type and select the corresponding strategy: + +| Question Type | Core Task | Focus Dimensions | +|---------------|-----------|------------------| +| **Concept Comparison** | Build comparison framework | Mechanism differences, applicability boundaries | +| **Decision Support** | Weigh trade-offs | Cost, risk, benefit | +| **Trend Analysis** | Map evolution trajectory | History, driving factors, predictions | +| **Problem Diagnosis** | Root cause analysis | Symptoms, causes, evidence chain | +| **Knowledge Organization** | Systematic structuring | Definitions, classifications, relationships | + +**Mode-specific classification**: + +| Mode / Phase | Typical Question Type | +|--------------|----------------------| +| Mode A Phase 1 | Knowledge Organization + Decision Support | +| Mode A Phase 2 | Decision Support | +| Mode B | Problem Diagnosis + Decision Support | + +### Step 0.5: Novelty Sensitivity Assessment (BLOCKING) + +**Before starting research, you must assess the novelty sensitivity of the question. This determines the source filtering strategy.** + +#### Novelty Sensitivity Classification + +| Sensitivity Level | Typical Domains | Source Time Window | Description | +|-------------------|-----------------|-------------------|-------------| +| **🔴 Critical** | AI/LLMs, blockchain, cryptocurrency | 3-6 months | Technology iterates extremely fast; info from months ago may be completely outdated | +| **🟠 High** | Cloud services, frontend frameworks, API interfaces | 6-12 months | Frequent version updates; must confirm current version | +| **🟡 Medium** | Programming languages, databases, operating systems | 1-2 years | Relatively stable but still evolving | +| **🟢 Low** | Algorithm fundamentals, design patterns, theoretical concepts | No limit | Core principles change slowly | + +#### 🔴 Critical Sensitivity Domain Special Rules + +When the research topic involves the following domains, **special rules must be enforced**: + +**Trigger word identification**: +- AI-related: LLM, GPT, Claude, Gemini, AI Agent, RAG, vector database, prompt engineering +- Cloud-native: Kubernetes new versions, Serverless, container runtimes +- Cutting-edge tech: Web3, quantum computing, AR/VR + +**Mandatory rules**: + +1. **Search with time constraints**: + - Use `time_range: "month"` or `time_range: "week"` to limit search results + - Prefer `start_date: "YYYY-MM-DD"` set to within the last 3 months + +2. **Elevate official source priority**: + - **Must first consult** official documentation, official blogs, official Changelogs + - GitHub Release Notes, official X/Twitter announcements + - Academic papers (arXiv and other preprint platforms) + +3. **Mandatory version number annotation**: + - Any technical description must annotate the **current version number** + - Example: "Claude 3.5 Sonnet (claude-3-5-sonnet-20241022) supports..." + - Prohibit vague statements like "the latest version supports..." + +4. **Outdated information handling**: + - Technical blogs/tutorials older than 6 months → historical reference only, **cannot serve as factual evidence** + - Version inconsistency found → must **verify current version** before using + - Obviously outdated descriptions (e.g., "will support in the future" but now already supported) → **discard directly** + +5. **Cross-validation**: + - Highly sensitive information must be confirmed from **at least 2 independent sources** + - Priority: Official docs > Official blogs > Authoritative tech media > Personal blogs + +6. **Official download/release page direct verification (BLOCKING)**: + - **Must directly visit** official download pages to verify platform support (don't rely on search engine caches) + - Use `mcp__tavily-mcp__tavily-extract` or `WebFetch` to directly extract download page content + - Example: `https://product.com/download` or `https://github.com/xxx/releases` + - Search results about "coming soon" or "planned support" may be outdated; must verify in real time + - **Platform support is frequently changing information**; cannot infer from old sources + +7. **Product-specific protocol/feature name search (BLOCKING)**: + - Beyond searching the product name, **must additionally search protocol/standard names the product supports** + - Common protocols/standards to search: + - AI tools: MCP, ACP (Agent Client Protocol), LSP, DAP + - Cloud services: OAuth, OIDC, SAML + - Data exchange: GraphQL, gRPC, REST + - Search format: `" support"` or `" integration"` + - These protocol integrations are often differentiating features, easily missed in main docs but documented in specialized pages + +#### Timeliness Assessment Output Template + +```markdown +## Timeliness Sensitivity Assessment + +- **Research Topic**: [topic] +- **Sensitivity Level**: 🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low +- **Rationale**: [why this level] +- **Source Time Window**: [X months/years] +- **Priority official sources to consult**: + 1. [Official source 1] + 2. [Official source 2] +- **Key version information to verify**: + - [Product/technology 1]: Current version ____ + - [Product/technology 2]: Current version ____ +``` + +**📁 Save action**: Append timeliness assessment to the end of `00_question_decomposition.md` + +--- + +### Step 1: Question Decomposition & Boundary Definition + +**Mode-specific sub-questions**: + +**Mode A Phase 2** (Initial Research — Problem & Solution): +- "What existing/competitor solutions address this problem?" +- "What are the component parts of this problem?" +- "For each component, what are the state-of-the-art solutions?" +- "What are the security considerations per component?" +- "What are the cost implications of each approach?" + +**Mode B** (Solution Assessment): +- "What are the weak points and potential problems in the existing draft?" +- "What are the security vulnerabilities in the proposed architecture?" +- "Where are the performance bottlenecks?" +- "What solutions exist for each identified issue?" + +**General sub-question patterns** (use when applicable): +- **Sub-question A**: "What is X and how does it work?" (Definition & mechanism) +- **Sub-question B**: "What are the dimensions of relationship/difference between X and Y?" (Comparative analysis) +- **Sub-question C**: "In what scenarios is X applicable/inapplicable?" (Boundary conditions) +- **Sub-question D**: "What are X's development trends/best practices?" (Extended analysis) + +**⚠️ Research Subject Boundary Definition (BLOCKING - must be explicit)**: + +When decomposing questions, you must explicitly define the **boundaries of the research subject**: + +| Dimension | Boundary to define | Example | +|-----------|--------------------|---------| +| **Population** | Which group is being studied? | University students vs K-12 vs vocational students vs all students | +| **Geography** | Which region is being studied? | Chinese universities vs US universities vs global | +| **Timeframe** | Which period is being studied? | Post-2020 vs full historical picture | +| **Level** | Which level is being studied? | Undergraduate vs graduate vs vocational | + +**Common mistake**: User asks about "university classroom issues" but sources include policies targeting "K-12 students" — mismatched target populations will invalidate the entire research. + +**📁 Save action**: +1. Read all files from INPUT_DIR to ground the research in the project context +2. Create working directory `RESEARCH_DIR//` +3. Write `00_question_decomposition.md`, including: + - Original question + - Active mode (A Phase 2 or B) and rationale + - Summary of relevant problem context from INPUT_DIR + - Classified question type and rationale + - **Research subject boundary definition** (population, geography, timeframe, level) + - List of decomposed sub-questions +4. Write TodoWrite to track progress + +### Step 2: Source Tiering & Authority Anchoring + +Tier sources by authority, **prioritize primary sources**: + +| Tier | Source Type | Purpose | Credibility | +|------|------------|---------|-------------| +| **L1** | Official docs, papers, specs, RFCs | Definitions, mechanisms, verifiable facts | ✅ High | +| **L2** | Official blogs, tech talks, white papers | Design intent, architectural thinking | ✅ High | +| **L3** | Authoritative media, expert commentary, tutorials | Supplementary intuition, case studies | ⚠️ Medium | +| **L4** | Community discussions, personal blogs, forums | Discover blind spots, validate understanding | ❓ Low | + +**L4 Community Source Specifics** (mandatory for product comparison research): + +| Source Type | Access Method | Value | +|------------|---------------|-------| +| **GitHub Issues** | Visit `github.com///issues` | Real user pain points, feature requests, bug reports | +| **GitHub Discussions** | Visit `github.com///discussions` | Feature discussions, usage insights, community consensus | +| **Reddit** | Search `site:reddit.com ""` | Authentic user reviews, comparison discussions | +| **Hacker News** | Search `site:news.ycombinator.com ""` | In-depth technical community discussions | +| **Discord/Telegram** | Product's official community channels | Active user feedback (must annotate [limited source]) | + +**Principles**: +- Conclusions must be traceable to L1/L2 +- L3/L4 serve only as supplementary and validation +- **L4 community discussions are used to discover "what users truly care about"** +- Record all information sources + +**⏰ Timeliness Filtering Rules (execute based on Step 0.5 sensitivity level)**: + +| Sensitivity Level | Source Filtering Rule | Suggested Search Parameters | +|-------------------|----------------------|-----------------------------| +| 🔴 Critical | Only accept sources within 6 months as factual evidence | `time_range: "month"` or `start_date` set to last 3 months | +| 🟠 High | Prefer sources within 1 year; annotate if older than 1 year | `time_range: "year"` | +| 🟡 Medium | Sources within 2 years used normally; older ones need validity check | Default search | +| 🟢 Low | No time limit | Default search | + +**High-Sensitivity Domain Search Strategy**: + +``` +1. Round 1: Targeted official source search + - Use include_domains to restrict to official domains + - Example: include_domains: ["anthropic.com", "openai.com", "docs.xxx.com"] + +2. Round 2: Official download/release page direct verification (BLOCKING) + - Directly visit official download pages; don't rely on search caches + - Use tavily-extract or WebFetch to extract page content + - Verify: platform support, current version number, release date + - This step is mandatory; search engines may cache outdated "Coming soon" info + +3. Round 3: Product-specific protocol/feature search (BLOCKING) + - Search protocol names the product supports (MCP, ACP, LSP, etc.) + - Format: `" " site:official_domain` + - These integration features are often not displayed on the main page but documented in specialized pages + +4. Round 4: Time-limited broad search + - time_range: "month" or start_date set to recent + - Exclude obviously outdated sources + +5. Round 5: Version verification + - Cross-validate version numbers from search results + - If inconsistency found, immediately consult official Changelog + +6. Round 6: Community voice mining (BLOCKING - mandatory for product comparison research) + - Visit the product's GitHub Issues page, review popular/pinned issues + - Search Issues for key feature terms (e.g., "MCP", "plugin", "integration") + - Review discussion trends from the last 3-6 months + - Identify the feature points and differentiating characteristics users care most about + - Value of this step: Official docs rarely emphasize "features we have that others don't", but community discussions do +``` + +**Community Voice Mining Detailed Steps**: + +``` +GitHub Issues Mining Steps: +1. Visit github.com///issues +2. Sort by "Most commented" to view popular discussions +3. Search keywords: + - Feature-related: feature request, enhancement, MCP, plugin, API + - Comparison-related: vs, compared to, alternative, migrate from +4. Review issue labels: enhancement, feature, discussion +5. Record frequently occurring feature demands and user pain points + +Value Translation: +- Frequently discussed features → likely differentiating highlights +- User complaints/requests → likely product weaknesses +- Comparison discussions → directly obtain user-perspective difference analysis +``` + +**Source Timeliness Annotation Template** (append to source registry): + +```markdown +- **Publication Date**: [YYYY-MM-DD] +- **Timeliness Status**: ✅ Currently valid / ⚠️ Needs verification / ❌ Outdated +- **Version Info**: [If applicable, annotate the relevant version number] +``` + +**Tool Usage**: +- Prefer `mcp__plugin_context7_context7__query-docs` for technical documentation +- Use `WebSearch` or `mcp__tavily-mcp__tavily-search` for broad searches +- Use `mcp__tavily-mcp__tavily-extract` to extract specific page content + +**⚠️ Target Audience Verification (BLOCKING - must check before inclusion)**: + +Before including each source, verify that its **target audience matches the research boundary**: + +| Source Type | Target audience to verify | Verification method | +|------------|---------------------------|---------------------| +| **Policy/Regulation** | Who is it for? (K-12/university/all) | Check document title, scope clauses | +| **Academic Research** | Who are the subjects? (vocational/undergraduate/graduate) | Check methodology/sample description sections | +| **Statistical Data** | Which population is measured? | Check data source description | +| **Case Reports** | What type of institution is involved? | Confirm institution type (university/high school/vocational) | + +**Handling mismatched sources**: +- Target audience completely mismatched → **do not include** +- Partially overlapping (e.g., "students" includes university students) → include but **annotate applicable scope** +- Usable as analogous reference (e.g., K-12 policy as a trend reference) → include but **explicitly annotate "reference only"** + +**📁 Save action**: +For each source consulted, **immediately** append to `01_source_registry.md`: +```markdown +## Source #[number] +- **Title**: [source title] +- **Link**: [URL] +- **Tier**: L1/L2/L3/L4 +- **Publication Date**: [YYYY-MM-DD] +- **Timeliness Status**: ✅ Currently valid / ⚠️ Needs verification / ❌ Outdated (reference only) +- **Version Info**: [If involving a specific version, must annotate] +- **Target Audience**: [Explicitly annotate the group/geography/level this source targets] +- **Research Boundary Match**: ✅ Full match / ⚠️ Partial overlap / 📎 Reference only +- **Summary**: [1-2 sentence key content] +- **Related Sub-question**: [which sub-question this corresponds to] +``` + +### Step 3: Fact Extraction & Evidence Cards + +Transform sources into **verifiable fact cards**: + +```markdown +## Fact Cards + +### Fact 1 +- **Statement**: [specific fact description] +- **Source**: [link/document section] +- **Confidence**: High/Medium/Low + +### Fact 2 +... +``` + +**Key discipline**: +- Pin down facts first, then reason +- Distinguish "what officials said" from "what I infer" +- When conflicting information is found, annotate and preserve both sides +- Annotate confidence level: + - ✅ High: Explicitly stated in official documentation + - ⚠️ Medium: Mentioned in official blog but not formally documented + - ❓ Low: Inference or from unofficial sources + +**📁 Save action**: +For each extracted fact, **immediately** append to `02_fact_cards.md`: +```markdown +## Fact #[number] +- **Statement**: [specific fact description] +- **Source**: [Source #number] [link] +- **Phase**: [Phase 1 / Phase 2 / Assessment] +- **Target Audience**: [which group this fact applies to, inherited from source or further refined] +- **Confidence**: ✅/⚠️/❓ +- **Related Dimension**: [corresponding comparison dimension] +``` + +**⚠️ Target audience in fact statements**: +- If a fact comes from a "partially overlapping" or "reference only" source, the statement **must explicitly annotate the applicable scope** +- Wrong: "The Ministry of Education banned phones in classrooms" (doesn't specify who) +- Correct: "The Ministry of Education banned K-12 students from bringing phones into classrooms (does not apply to university students)" + +### Step 4: Build Comparison/Analysis Framework + +Based on the question type, select fixed analysis dimensions: + +**General Dimensions** (select as needed): +1. Goal / What problem does it solve +2. Working mechanism / Process +3. Input / Output / Boundaries +4. Advantages / Disadvantages / Trade-offs +5. Applicable scenarios / Boundary conditions +6. Cost / Benefit / Risk +7. Historical evolution / Future trends +8. Security / Permissions / Controllability + +**Concept Comparison Specific Dimensions**: +1. Definition & essence +2. Trigger / invocation method +3. Execution agent +4. Input/output & type constraints +5. Determinism & repeatability +6. Resource & context management +7. Composition & reuse patterns +8. Security boundaries & permission control + +**Decision Support Specific Dimensions**: +1. Solution overview +2. Implementation cost +3. Maintenance cost +4. Risk assessment +5. Expected benefit +6. Applicable scenarios +7. Team capability requirements +8. Migration difficulty + +**📁 Save action**: +Write to `03_comparison_framework.md`: +```markdown +# Comparison Framework + +## Selected Framework Type +[Concept Comparison / Decision Support / ...] + +## Selected Dimensions +1. [Dimension 1] +2. [Dimension 2] +... + +## Initial Population +| Dimension | X | Y | Factual Basis | +|-----------|---|---|---------------| +| [Dimension 1] | [description] | [description] | Fact #1, #3 | +| ... | | | | +``` + +### Step 5: Reference Point Baseline Alignment + +Ensure all compared parties have clear, consistent definitions: + +**Checklist**: +- [ ] Is the reference point's definition stable/widely accepted? +- [ ] Does it need verification, or can domain common knowledge be used? +- [ ] Does the reader's understanding of the reference point match mine? +- [ ] Are there ambiguities that need to be clarified first? + +### Step 6: Fact-to-Conclusion Reasoning Chain + +Explicitly write out the "fact → comparison → conclusion" reasoning process: + +```markdown +## Reasoning Process + +### Regarding [Dimension Name] + +1. **Fact confirmation**: According to [source], X's mechanism is... +2. **Compare with reference**: While Y's mechanism is... +3. **Conclusion**: Therefore, the difference between X and Y on this dimension is... +``` + +**Key discipline**: +- Conclusions come from mechanism comparison, not "gut feelings" +- Every conclusion must be traceable to specific facts +- Uncertain conclusions must be annotated + +**📁 Save action**: +Write to `04_reasoning_chain.md`: +```markdown +# Reasoning Chain + +## Dimension 1: [Dimension Name] + +### Fact Confirmation +According to [Fact #X], X's mechanism is... + +### Reference Comparison +While Y's mechanism is... (Source: [Fact #Y]) + +### Conclusion +Therefore, the difference between X and Y on this dimension is... + +### Confidence +✅/⚠️/❓ + rationale + +--- +## Dimension 2: [Dimension Name] +... +``` + +### Step 7: Use-Case Validation (Sanity Check) + +Validate conclusions against a typical scenario: + +**Validation questions**: +- Based on my conclusions, how should this scenario be handled? +- Is that actually the case? +- Are there counterexamples that need to be addressed? + +**Review checklist**: +- [ ] Are draft conclusions consistent with Step 3 fact cards? +- [ ] Are there any important dimensions missed? +- [ ] Is there any over-extrapolation? +- [ ] Are conclusions actionable/verifiable? + +**📁 Save action**: +Write to `05_validation_log.md`: +```markdown +# Validation Log + +## Validation Scenario +[Scenario description] + +## Expected Based on Conclusions +If using X: [expected behavior] +If using Y: [expected behavior] + +## Actual Validation Results +[actual situation] + +## Counterexamples +[yes/no, describe if yes] + +## Review Checklist +- [x] Draft conclusions consistent with fact cards +- [x] No important dimensions missed +- [x] No over-extrapolation +- [ ] Issue found: [if any] + +## Conclusions Requiring Revision +[if any] +``` + +### Step 8: Deliverable Formatting + +Make the output **readable, traceable, and actionable**. + +**📁 Save action**: +Integrate all intermediate artifacts. Write to `OUTPUT_DIR/solution_draft##.md` using the appropriate output template based on active mode: +- Mode A: `templates/solution_draft_mode_a.md` +- Mode B: `templates/solution_draft_mode_b.md` + +Sources to integrate: +- Extract background from `00_question_decomposition.md` +- Reference key facts from `02_fact_cards.md` +- Organize conclusions from `04_reasoning_chain.md` +- Generate references from `01_source_registry.md` +- Supplement with use cases from `05_validation_log.md` +- For Mode A: include AC assessment from `00_ac_assessment.md` + +## Solution Draft Output Templates + +### Mode A: Initial Research Output + +Use template: `templates/solution_draft_mode_a.md` + +### Mode B: Solution Assessment Output + +Use template: `templates/solution_draft_mode_b.md` + +## Stakeholder Perspectives + +Adjust content depth based on audience: + +| Audience | Focus | Detail Level | +|----------|-------|--------------| +| **Decision-makers** | Conclusions, risks, recommendations | Concise, emphasize actionability | +| **Implementers** | Specific mechanisms, how-to | Detailed, emphasize how to do it | +| **Technical experts** | Details, boundary conditions, limitations | In-depth, emphasize accuracy | + +## Output Files + +Default intermediate artifacts location: `RESEARCH_DIR//` + +**Required files** (automatically generated through the process): + +| File | Content | When Generated | +|------|---------|----------------| +| `00_ac_assessment.md` | AC & restrictions assessment (Mode A only) | After Phase 1 completion | +| `00_question_decomposition.md` | Question type, sub-question list | After Step 0-1 completion | +| `01_source_registry.md` | All source links and summaries | Continuously updated during Step 2 | +| `02_fact_cards.md` | Extracted facts and sources | Continuously updated during Step 3 | +| `03_comparison_framework.md` | Selected framework and populated data | After Step 4 completion | +| `04_reasoning_chain.md` | Fact → conclusion reasoning | After Step 6 completion | +| `05_validation_log.md` | Use-case validation and review | After Step 7 completion | +| `OUTPUT_DIR/solution_draft##.md` | Complete solution draft | After Step 8 completion | +| `OUTPUT_DIR/tech_stack.md` | Tech stack evaluation and decisions | After Phase 3 (optional) | +| `OUTPUT_DIR/security_analysis.md` | Threat model and security controls | After Phase 4 (optional) | + +**Optional files**: +- `raw/*.md` - Raw source archives (saved when content is lengthy) + +## Methodology Quick Reference Card + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Deep Research — Mode-Aware 8-Step Method │ +├──────────────────────────────────────────────────────────────────┤ +│ CONTEXT: Resolve mode (project vs standalone) + set paths │ +│ GUARDRAILS: Check INPUT_DIR/INPUT_FILE exists + required files │ +│ MODE DETECT: solution_draft*.md in 01_solution? → A or B │ +│ │ +│ MODE A: Initial Research │ +│ Phase 1: AC & Restrictions Assessment (BLOCKING) │ +│ Phase 2: Full 8-step → solution_draft##.md │ +│ Phase 3: Tech Stack Consolidation (OPTIONAL) → tech_stack.md │ +│ Phase 4: Security Deep Dive (OPTIONAL) → security_analysis.md │ +│ │ +│ MODE B: Solution Assessment │ +│ Read latest draft → Full 8-step → solution_draft##.md (N+1) │ +│ Optional: Phase 3 / Phase 4 on revised draft │ +│ │ +│ 8-STEP ENGINE: │ +│ 0. Classify question type → Select framework template │ +│ 1. Decompose question → mode-specific sub-questions │ +│ 2. Tier sources → L1 Official > L2 Blog > L3 Media > L4 │ +│ 3. Extract facts → Each with source, confidence level │ +│ 4. Build framework → Fixed dimensions, structured compare │ +│ 5. Align references → Ensure unified definitions │ +│ 6. Reasoning chain → Fact→Compare→Conclude, explicit │ +│ 7. Use-case validation → Sanity check, prevent armchairing │ +│ 8. Deliverable → solution_draft##.md (mode-specific format) │ +├──────────────────────────────────────────────────────────────────┤ +│ Key discipline: Ask don't assume · Facts before reasoning │ +│ Conclusions from mechanism, not gut feelings │ +└──────────────────────────────────────────────────────────────────┘ +``` + +## Usage Examples + +### Example 1: Initial Research (Mode A) + +``` +User: Research this problem and find the best solution +``` + +Execution flow: +1. Context resolution: no explicit file → project mode (INPUT_DIR=`_docs/00_problem/`, OUTPUT_DIR=`_docs/01_solution/`) +2. Guardrails: verify INPUT_DIR exists with required files +3. Mode detection: no `solution_draft*.md` → Mode A +4. Phase 1: Assess acceptance criteria and restrictions, ask user about unclear parts +5. BLOCKING: present AC assessment, wait for user confirmation +6. Phase 2: Full 8-step research — competitors, components, state-of-the-art solutions +7. Output: `OUTPUT_DIR/solution_draft01.md` +8. (Optional) Phase 3: Tech stack consolidation → `tech_stack.md` +9. (Optional) Phase 4: Security deep dive → `security_analysis.md` + +### Example 2: Solution Assessment (Mode B) + +``` +User: Assess the current solution draft +``` + +Execution flow: +1. Context resolution: no explicit file → project mode +2. Guardrails: verify INPUT_DIR exists +3. Mode detection: `solution_draft03.md` found in OUTPUT_DIR → Mode B, read it as input +4. Full 8-step research — weak points, security, performance, solutions +5. Output: `OUTPUT_DIR/solution_draft04.md` with findings table + revised draft + +### Example 3: Standalone Research + +``` +User: /research @my_problem.md +``` + +Execution flow: +1. Context resolution: explicit file → standalone mode (INPUT_FILE=`my_problem.md`, OUTPUT_DIR=`_standalone/my_problem/01_solution/`) +2. Guardrails: verify INPUT_FILE exists and is non-empty, warn about missing restrictions/AC +3. Mode detection + full research flow as in Example 1, scoped to standalone paths +4. Output: `_standalone/my_problem/01_solution/solution_draft01.md` + +### Example 4: Force Initial Research (Override) + +``` +User: Research from scratch, ignore existing drafts +``` + +Execution flow: +1. Context resolution: no explicit file → project mode +2. Mode detection: drafts exist, but user explicitly requested initial research → Mode A +3. Phase 1 + Phase 2 as in Example 1 +4. Output: `OUTPUT_DIR/solution_draft##.md` (incremented from highest existing) + +## Source Verifiability Requirements + +**Core principle**: Every piece of external information cited in the report must be directly verifiable by the user. + +**Mandatory rules**: + +1. **URL Accessibility**: + - All cited links must be publicly accessible (no login/paywall required) + - If citing content that requires login, must annotate `[login required]` + - If citing academic papers, prefer publicly available versions (arXiv/DOI) + +2. **Citation Precision**: + - For long documents, must specify exact section/page/timestamp + - Example: `[Source: OpenAI Blog, 2024-03-15, "GPT-4 Technical Report", §3.2 Safety]` + - Video/audio citations need timestamps + +3. **Content Correspondence**: + - Cited facts must have corresponding statements in the original text + - Prohibit over-interpretation of original text presented as "citations" + - If there's interpretation/inference, must explicitly annotate "inferred based on [source]" + +4. **Timeliness Annotation**: + - Annotate source publication/update date + - For technical docs, annotate version number + - Sources older than 2 years need validity assessment + +5. **Handling Unverifiable Information**: + - If the information source cannot be publicly verified (e.g., private communication, paywalled report excerpts), must annotate `[limited source]` in confidence level + - Unverifiable information cannot be the sole support for core conclusions + +## Quality Checklist + +Before completing the solution draft, check the following items: + +### General Quality + +- [ ] All core conclusions have L1/L2 tier factual support +- [ ] No use of vague words like "possibly", "probably" without annotating uncertainty +- [ ] Comparison dimensions are complete with no key differences missed +- [ ] At least one real use case validates conclusions +- [ ] References are complete with accessible links +- [ ] **Every citation can be directly verified by the user (source verifiability)** +- [ ] Structure hierarchy is clear; executives can quickly locate information + +### Mode A Specific + +- [ ] **Phase 1 completed**: AC assessment was presented to and confirmed by user +- [ ] **AC assessment consistent**: Solution draft respects the (possibly adjusted) acceptance criteria and restrictions +- [ ] **Competitor analysis included**: Existing solutions were researched +- [ ] **All components have comparison tables**: Each component lists alternatives with tools, advantages, limitations, security, cost +- [ ] **Tools/libraries verified**: Suggested tools actually exist and work as described +- [ ] **Testing strategy covers AC**: Tests map to acceptance criteria +- [ ] **Tech stack documented** (if Phase 3 ran): `tech_stack.md` has evaluation tables, risk assessment, and learning requirements +- [ ] **Security analysis documented** (if Phase 4 ran): `security_analysis.md` has threat model and per-component controls + +### Mode B Specific + +- [ ] **Findings table complete**: All identified weak points documented with solutions +- [ ] **Weak point categories covered**: Functional, security, and performance assessed +- [ ] **New draft is self-contained**: Written as if from scratch, no "updated" markers +- [ ] **Performance column included**: Mode B comparison tables include performance characteristics +- [ ] **Previous draft issues addressed**: Every finding in the table is resolved in the new draft + +### ⏰ Timeliness Check (High-Sensitivity Domain BLOCKING) + +When the research topic has 🔴 Critical or 🟠 High sensitivity level, **the following checks must be completed**: + +- [ ] **Timeliness sensitivity assessment completed**: `00_question_decomposition.md` contains a timeliness assessment section +- [ ] **Source timeliness annotated**: Every source has publication date, timeliness status, version info +- [ ] **No outdated sources used as factual evidence**: + - 🔴 Critical: Core fact sources are all within 6 months + - 🟠 High: Core fact sources are all within 1 year +- [ ] **Version numbers explicitly annotated**: + - Technical product/API/SDK descriptions all annotate specific version numbers + - No vague time expressions like "latest version" or "currently" +- [ ] **Official sources prioritized**: Core conclusions have support from official documentation/blogs +- [ ] **Cross-validation completed**: Key technical information confirmed from at least 2 independent sources +- [ ] **Download page directly verified**: Platform support info comes from real-time extraction of official download pages, not search caches +- [ ] **Protocol/feature names searched**: Searched for product-supported protocol names (MCP, ACP, etc.) +- [ ] **GitHub Issues mined**: Reviewed product's GitHub Issues popular discussions +- [ ] **Community hotspots identified**: Identified and recorded feature points users care most about + +**Typical community voice oversight error cases**: + +> Wrong: Relying solely on official docs, MCP briefly mentioned as a regular feature in the report +> Correct: Discovered through GitHub Issues that MCP is the most hotly discussed feature in the community, expanded analysis of its value in the report + +> Wrong: "Both Alma and Cherry Studio support MCP" (no difference analysis) +> Correct: Discovered through community discussion that "Alma's MCP implementation is highly consistent with Claude Code — this is its core competitive advantage" + +**Typical platform support/protocol oversight error cases**: + +> Wrong: "Alma only supports macOS" (based on search engine cached "Coming soon" info) +> Correct: Directly visited alma.now/download page to verify currently supported platforms + +> Wrong: "Alma supports MCP" (only searched MCP, missed ACP) +> Correct: Searched both "Alma MCP" and "Alma ACP", discovered Alma also supports ACP protocol integration for CLI tools + +**Typical timeliness error cases**: + +> Wrong: "Claude supports function calling" (no version annotated, may refer to old version capabilities) +> Correct: "Claude 3.5 Sonnet (claude-3-5-sonnet-20241022) supports function calling via Tool Use API, with a maximum of 8192 tokens for tool definitions" + +> Wrong: "According to a 2023 blog post, GPT-4's context length is 8K" +> Correct: "As of January 2024, GPT-4 Turbo supports 128K context (Source: OpenAI official documentation, updated 2024-01-25)" + +### ⚠️ Target Audience Consistency Check (BLOCKING) + +This is the most easily overlooked and most critical check item: + +- [ ] **Research boundary clearly defined**: `00_question_decomposition.md` has clear population/geography/timeframe/level boundaries +- [ ] **Every source has target audience annotated**: `01_source_registry.md` has "Target Audience" and "Research Boundary Match" fields for each source +- [ ] **Mismatched sources properly handled**: + - Completely mismatched sources were not included + - Partially overlapping sources have annotated applicable scope + - Reference-only sources are explicitly annotated +- [ ] **No audience confusion in fact cards**: Every fact in `02_fact_cards.md` has a target audience consistent with the research boundary +- [ ] **No audience confusion in the report**: Policies/research/data cited in the solution draft have target audiences consistent with the research topic + +**Typical error case**: +> Research topic: "University students not paying attention in class" +> Wrong citation: "In October 2025, the Ministry of Education banned phones in classrooms" +> Problem: That policy targets K-12 students, not university students +> Consequence: Readers mistakenly believe the Ministry of Education banned university students from carrying phones — severely misleading + +## Final Reply Guidelines + +When replying to the user after research is complete: + +**✅ Should include**: +- Active mode used (A or B) and which optional phases were executed +- One-sentence core conclusion +- Key findings summary (3-5 points) +- Path to the solution draft: `OUTPUT_DIR/solution_draft##.md` +- Paths to optional artifacts if produced: `tech_stack.md`, `security_analysis.md` +- If there are significant uncertainties, annotate points requiring further verification + +**❌ Must not include**: +- Process file listings (e.g., `00_question_decomposition.md`, `01_source_registry.md`, etc.) +- Detailed research step descriptions +- Working directory structure display + +**Reason**: Process files are for retrospective review, not for the user. The user cares about conclusions, not the process. diff --git a/.cursor/skills/research/templates/solution_draft_mode_a.md b/.cursor/skills/research/templates/solution_draft_mode_a.md new file mode 100644 index 0000000..94773c3 --- /dev/null +++ b/.cursor/skills/research/templates/solution_draft_mode_a.md @@ -0,0 +1,37 @@ +# Solution Draft + +## Product Solution Description +[Short description of the proposed solution. Brief component interaction diagram.] + +## Existing/Competitor Solutions Analysis +[Analysis of existing solutions for similar problems, if any.] + +## Architecture + +[Architecture solution that meets restrictions and acceptance criteria.] + +### Component: [Component Name] + +| Solution | Tools | Advantages | Limitations | Requirements | Security | Cost | Fit | +|----------|-------|-----------|-------------|-------------|----------|------|-----| +| [Option 1] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [cost] | [fit assessment] | +| [Option 2] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [cost] | [fit assessment] | + +[Repeat per component] + +## Testing Strategy + +### Integration / Functional Tests +- [Test 1] +- [Test 2] + +### Non-Functional Tests +- [Performance test 1] +- [Security test 1] + +## References +[All cited source links] + +## Related Artifacts +- Tech stack evaluation: `_docs/01_solution/tech_stack.md` (if Phase 3 was executed) +- Security analysis: `_docs/01_solution/security_analysis.md` (if Phase 4 was executed) diff --git a/.cursor/skills/research/templates/solution_draft_mode_b.md b/.cursor/skills/research/templates/solution_draft_mode_b.md new file mode 100644 index 0000000..67b1422 --- /dev/null +++ b/.cursor/skills/research/templates/solution_draft_mode_b.md @@ -0,0 +1,40 @@ +# Solution Draft + +## Assessment Findings + +| Old Component Solution | Weak Point (functional/security/performance) | New Solution | +|------------------------|----------------------------------------------|-------------| +| [old] | [weak point] | [new] | + +## Product Solution Description +[Short description. Brief component interaction diagram. Written as if from scratch — no "updated" markers.] + +## Architecture + +[Architecture solution that meets restrictions and acceptance criteria.] + +### Component: [Component Name] + +| Solution | Tools | Advantages | Limitations | Requirements | Security | Performance | Fit | +|----------|-------|-----------|-------------|-------------|----------|------------|-----| +| [Option 1] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [perf] | [fit assessment] | +| [Option 2] | [lib/platform] | [pros] | [cons] | [reqs] | [security] | [perf] | [fit assessment] | + +[Repeat per component] + +## Testing Strategy + +### Integration / Functional Tests +- [Test 1] +- [Test 2] + +### Non-Functional Tests +- [Performance test 1] +- [Security test 1] + +## References +[All cited source links] + +## Related Artifacts +- Tech stack evaluation: `_docs/01_solution/tech_stack.md` (if Phase 3 was executed) +- Security analysis: `_docs/01_solution/security_analysis.md` (if Phase 4 was executed) diff --git a/.cursor/skills/security/SKILL.md b/.cursor/skills/security/SKILL.md new file mode 100644 index 0000000..ceab368 --- /dev/null +++ b/.cursor/skills/security/SKILL.md @@ -0,0 +1,311 @@ +--- +name: security-testing +description: "Test for security vulnerabilities using OWASP principles. Use when conducting security audits, testing auth, or implementing security practices." +category: specialized-testing +priority: critical +tokenEstimate: 1200 +agents: [qe-security-scanner, qe-api-contract-validator, qe-quality-analyzer] +implementation_status: optimized +optimization_version: 1.0 +last_optimized: 2025-12-02 +dependencies: [] +quick_reference_card: true +tags: [security, owasp, sast, dast, vulnerabilities, auth, injection] +trust_tier: 3 +validation: + schema_path: schemas/output.json + validator_path: scripts/validate-config.json + eval_path: evals/security-testing.yaml +--- + +# Security Testing + + +When testing security or conducting audits: +1. TEST OWASP Top 10 vulnerabilities systematically +2. VALIDATE authentication and authorization on every endpoint +3. SCAN dependencies for known vulnerabilities (npm audit) +4. CHECK for injection attacks (SQL, XSS, command) +5. VERIFY secrets aren't exposed in code/logs + +**Quick Security Checks:** +- Access control → Test horizontal/vertical privilege escalation +- Crypto → Verify password hashing, HTTPS, no sensitive data exposed +- Injection → Test SQL injection, XSS, command injection +- Auth → Test weak passwords, session fixation, MFA enforcement +- Config → Check error messages don't leak info + +**Critical Success Factors:** +- Think like an attacker, build like a defender +- Security is built in, not added at the end +- Test continuously in CI/CD, not just before release + + +## Quick Reference Card + +### When to Use +- Security audits and penetration testing +- Testing authentication/authorization +- Validating input sanitization +- Reviewing security configuration + +### OWASP Top 10 (2021) +| # | Vulnerability | Key Test | +|---|---------------|----------| +| 1 | Broken Access Control | User A accessing User B's data | +| 2 | Cryptographic Failures | Plaintext passwords, HTTP | +| 3 | Injection | SQL/XSS/command injection | +| 4 | Insecure Design | Rate limiting, session timeout | +| 5 | Security Misconfiguration | Verbose errors, exposed /admin | +| 6 | Vulnerable Components | npm audit, outdated packages | +| 7 | Auth Failures | Weak passwords, no MFA | +| 8 | Integrity Failures | Unsigned updates, malware | +| 9 | Logging Failures | No audit trail for breaches | +| 10 | SSRF | Server fetching internal URLs | + +### Tools +| Type | Tool | Purpose | +|------|------|---------| +| SAST | SonarQube, Semgrep | Static code analysis | +| DAST | OWASP ZAP, Burp | Dynamic scanning | +| Deps | npm audit, Snyk | Dependency vulnerabilities | +| Secrets | git-secrets, TruffleHog | Secret scanning | + +### Agent Coordination +- `qe-security-scanner`: Multi-layer SAST/DAST scanning +- `qe-api-contract-validator`: API security testing +- `qe-quality-analyzer`: Security code review + +--- + +## Key Vulnerability Tests + +### 1. Broken Access Control +```javascript +// Horizontal escalation - User A accessing User B's data +test('user cannot access another user\'s order', async () => { + const userAToken = await login('userA'); + const userBOrder = await createOrder('userB'); + + const response = await api.get(`/orders/${userBOrder.id}`, { + headers: { Authorization: `Bearer ${userAToken}` } + }); + expect(response.status).toBe(403); +}); + +// Vertical escalation - Regular user accessing admin +test('regular user cannot access admin', async () => { + const userToken = await login('regularUser'); + expect((await api.get('/admin/users', { + headers: { Authorization: `Bearer ${userToken}` } + })).status).toBe(403); +}); +``` + +### 2. Injection Attacks +```javascript +// SQL Injection +test('prevents SQL injection', async () => { + const malicious = "' OR '1'='1"; + const response = await api.get(`/products?search=${malicious}`); + expect(response.body.length).toBeLessThan(100); // Not all products +}); + +// XSS +test('sanitizes HTML output', async () => { + const xss = ''; + await api.post('/comments', { text: xss }); + + const html = (await api.get('/comments')).body; + expect(html).toContain('<script>'); + expect(html).not.toContain('