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/.cursor/commands/deploy.md b/.cursor/commands/deploy.md new file mode 100644 index 0000000..4605aa2 --- /dev/null +++ b/.cursor/commands/deploy.md @@ -0,0 +1,71 @@ +# Deployment Strategy Planning + +## Initial data: + - Problem description: `@_docs/00_problem/problem_description.md` + - Restrictions: `@_docs/00_problem/restrictions.md` + - Full Solution Description: `@_docs/01_solution/solution.md` + - Components: `@_docs/02_components` + - Environment Strategy: `@_docs/00_templates/environment_strategy.md` + +## Role + You are a DevOps/Platform engineer + +## Task + - Define deployment strategy for each environment + - Plan deployment procedures and automation + - Define rollback procedures + - Establish deployment verification steps + - Document manual intervention points + +## Output + +### Deployment Architecture + - Infrastructure diagram (where components run) + - Network topology + - Load balancing strategy + - Container/VM configuration + +### Deployment Procedures + +#### Staging Deployment + - Trigger conditions + - Pre-deployment checks + - Deployment steps + - Post-deployment verification + - Smoke tests to run + +#### Production Deployment + - Approval workflow + - Deployment window + - Pre-deployment checks + - Deployment steps (blue-green, rolling, canary) + - Post-deployment verification + - Smoke tests to run + +### Rollback Procedures + - Rollback trigger criteria + - Rollback steps per environment + - Data rollback considerations + - Communication plan during rollback + +### Health Checks + - Liveness probe configuration + - Readiness probe configuration + - Custom health endpoints + +### Deployment Checklist + - [ ] All tests pass in CI + - [ ] Security scan clean + - [ ] Database migrations reviewed + - [ ] Feature flags configured + - [ ] Monitoring alerts configured + - [ ] Rollback plan documented + - [ ] Stakeholders notified + +Store output to `_docs/02_components/deployment_strategy.md` + +## Notes + - Prefer automated deployments over manual + - 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/.cursor/commands/implement-cicd.md b/.cursor/commands/implement-cicd.md new file mode 100644 index 0000000..282ec2c --- /dev/null +++ b/.cursor/commands/implement-cicd.md @@ -0,0 +1,64 @@ +# CI/CD Pipeline Validation & Enhancement + +## Initial data: + - Problem description: `@_docs/00_problem/problem_description.md` + - Restrictions: `@_docs/00_problem/restrictions.md` + - Full Solution Description: `@_docs/01_solution/solution.md` + - Components: `@_docs/02_components` + - Environment Strategy: `@_docs/00_templates/environment_strategy.md` + +## Role + You are a DevOps engineer + +## Task + - Review existing CI/CD pipeline configuration + - Validate all stages are working correctly + - Optimize pipeline performance (parallelization, caching) + - Ensure test coverage gates are enforced + - Verify security scanning is properly configured + - Add missing quality gates + +## Checklist + +### Pipeline Health + - [ ] All stages execute successfully + - [ ] Build time is acceptable (<10 min for most projects) + - [ ] Caching is properly configured (dependencies, build artifacts) + - [ ] Parallel execution where possible + +### Quality Gates + - [ ] Code coverage threshold enforced (minimum 75%) + - [ ] Linting errors block merge + - [ ] Security vulnerabilities block merge (critical/high) + - [ ] All tests must pass + +### Environment Deployments + - [ ] Staging deployment works on merge to stage branch + - [ ] Environment variables properly configured per environment + - [ ] Secrets are securely managed (not in code) + - [ ] Rollback procedure documented + +### Monitoring + - [ ] Build notifications configured (Slack, email, etc.) + - [ ] Failed build alerts + - [ ] Deployment success/failure notifications + +## Output + +### Pipeline Status Report + - Current pipeline configuration summary + - Issues found and fixes applied + - Performance metrics (build times) + +### Recommended Improvements + - Short-term improvements + - Long-term optimizations + +### Quality Gate Configuration + - Thresholds configured + - Enforcement rules + +## Notes + - Do not break existing functionality + - Test changes in separate branch first + - Document any manual steps required diff --git a/.cursor/commands/implement-code-review.md b/.cursor/commands/implement-code-review.md new file mode 100644 index 0000000..ef99112 --- /dev/null +++ b/.cursor/commands/implement-code-review.md @@ -0,0 +1,38 @@ +# Code Review + +## Initial data: + - Problem description: `@_docs/00_problem/problem_description.md`. + - Acceptance criteria: `@_docs/00_problem/acceptance_criteria.md`. + - Security approach: `@_docs/00_problem/security_approach.md`. + - Full Solution Description: `@_docs/01_solution/solution.md` + - Components: `@_docs/02_components` + +## Role + You are a senior software engineer performing code review + +## Task + - Review implemented code against component specifications + - Check code quality: readability, maintainability, SOLID principles + - Check error handling consistency + - Check logging implementation + - Check security requirements are met + - Check test coverage is adequate + - Identify code smells and technical debt + +## Output + ### Issues Found + For each issue: + - File/Location + - Issue type (Bug/Security/Performance/Style/Debt) + - Description + - Suggested fix + - Priority (High/Medium/Low) + + ### Summary + - Total issues by type + - Blocking issues that must be fixed + - Recommended improvements + +## 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/.cursor/commands/observability.md b/.cursor/commands/observability.md new file mode 100644 index 0000000..a9be136 --- /dev/null +++ b/.cursor/commands/observability.md @@ -0,0 +1,122 @@ +# Observability Planning + +## Initial data: + - Problem description: `@_docs/00_problem/problem_description.md` + - Full Solution Description: `@_docs/01_solution/solution.md` + - Components: `@_docs/02_components` + - Deployment Strategy: `@_docs/02_components/deployment_strategy.md` + +## Role + You are a Site Reliability Engineer (SRE) + +## Task + - Define logging strategy across all components + - Plan metrics collection and dashboards + - Design distributed tracing (if applicable) + - Establish alerting rules + - Document incident response procedures + +## Output + +### Logging Strategy + +#### Log Levels +| Level | Usage | Example | +|-------|-------|---------| +| ERROR | Exceptions, failures requiring attention | Database connection failed | +| WARN | Potential issues, degraded performance | Retry attempt 2/3 | +| INFO | Significant business events | User registered, Order placed | +| DEBUG | Detailed diagnostic information | Request payload, Query params | + +#### Log Format +```json +{ + "timestamp": "ISO8601", + "level": "INFO", + "service": "service-name", + "correlation_id": "uuid", + "message": "Event description", + "context": {} +} +``` + +#### Log Storage +- Development: Console/file +- Staging: Centralized (ELK, CloudWatch, etc.) +- Production: Centralized with retention policy + +### Metrics + +#### System Metrics +- CPU usage +- Memory usage +- Disk I/O +- Network I/O + +#### Application Metrics +| Metric | Type | Description | +|--------|------|-------------| +| request_count | Counter | Total requests | +| request_duration | Histogram | Response time | +| error_count | Counter | Failed requests | +| active_connections | Gauge | Current connections | + +#### Business Metrics +- [Define based on acceptance criteria] + +### Distributed Tracing + +#### Trace Context +- Correlation ID propagation +- Span naming conventions +- Sampling strategy + +#### Integration Points +- HTTP headers +- Message queue metadata +- Database query tagging + +### Alerting + +#### Alert Categories +| Severity | Response Time | Examples | +|----------|---------------|----------| +| Critical | 5 min | Service down, Data loss | +| High | 30 min | High error rate, Performance degradation | +| Medium | 4 hours | Elevated latency, Disk usage high | +| Low | Next business day | Non-critical warnings | + +#### Alert Rules +```yaml +alerts: + - name: high_error_rate + condition: error_rate > 5% + duration: 5m + severity: high + + - name: service_down + condition: health_check_failed + duration: 1m + severity: critical +``` + +### Dashboards + +#### Operations Dashboard +- Service health status +- Request rate and error rate +- Response time percentiles +- Resource utilization + +#### Business Dashboard +- Key business metrics +- User activity +- Transaction volumes + +Store output to `_docs/02_components/observability_plan.md` + +## Notes + - Follow the principle: "If it's not monitored, it's not in production" + - 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..9b7b37c --- /dev/null +++ b/.cursor/skills/research/SKILL.md @@ -0,0 +1,1090 @@ +--- +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 + +**📁 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('