Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# Create a Detailed, Verifiable Task Plan
7 
8**Your Core Task: Generate a multi-commit task plan file, saved as `docs/tasks/<YYYY-MM-DD-HH-MM-task-name>.md`. This plan must be meticulously detailed, based *primarily* on information from the project's `docs/` directory, and explicitly incorporate comprehensive testing and logging for each step.**
9 
10## File Existence Check
11 
12Verify key documentation files before planning:
13 
14```bash
15ls . docs
16```
17 
18Use the results to tailor the task plan.
19 
20## I. Pre-computation: Capture Timestamp
21 
221.  **Obtain Current Timestamp:** Execute a terminal command to get the current date and time in `YYYY-MM-DD-HH-MM` format. (Example for Linux/macOS: `date +"%Y-%m-%d-%H-%M"`).
232.  **Formulate Filename:** Use this timestamp and a descriptive task name (derived from user request or PRD) to construct the full filename, e.g., `docs/tasks/2023-10-27-14-35-implement-user-auth.md`.
24 
25## II. Information Gathering (CRITICAL PRE-REQUISITE)
26 
27- **Mandatory Context Review:** Before writing any part of the plan, you **MUST** find and thoroughly read all relevant files in the project's `docs/` directory. This is not optional.
28- **Prioritized Documents:** Pay special attention to (if they exist):
29    - `docs/PRD.md` (Product Requirements Document)
30    - `docs/TECH_STACK.md`
31    - `docs/openapi.yaml` (or similar API specifications)
32    - `docs/logging.md`, `docs/LOGGING_GUIDE.md` (or any docs related to logging practices)
33    - `docs/TEST_STRATEGY.md`, `docs/TESTING_GUIDELINES.md` (or any docs related to testing)
34    - `NOTES.md` (if present at project root or in `docs/`)
35- **Purpose:** This information is *essential* for creating an accurate, relevant, and genuinely useful task plan that aligns with project standards.
36 
37## III. Core Directive: Construct the Task Plan File
38 
39Create the content for the `docs/tasks/<YYYY-MM-DD-HH-MM-task-name>.md` file. This file outlines a step-by-step plan, broken down into a series of distinct commits (typically 2-5 commits per task). Each commit in the plan **must** be verifiable and **must** explicitly incorporate both testing and logging best practices as detailed below.
40 
41### A. Strict Operational Constraints
42 
43- **File Operations:**
44    - You are **ONLY** permitted to write to the specific task plan file you are creating (e.g., `docs/tasks/YYYY-MM-DD-HH-MM-task-name.md`).
45    - Reading project documentation from `docs/` (as specified above) is **MANDATORY** to inform the plan.
46- **Communication Protocol:**
47    - **NO Conversational Output:** You are forbidden from generating any conversational output, commentary, preamble, or summaries *before* or *during* the creation of the task plan file content.
48    - **Output is the File Content:** Your *entire* output for this specific rule invocation must be *only* the complete, raw Markdown content of the `docs/tasks/<YYYY-MM-DD-HH-MM-task-name>.md` file.
49- **User Interaction:**
50    - You receive the initial task description from the user.
51    - If, after a **thorough review** of all available `docs/` materials, the task description remains insufficient to create a coherent and specific plan, you **MUST** indicate this *within* the task plan file itself using the HTML comment format: `<!-- TODO: [Specify missing information and reference document, e.g., 'Need API endpoint for user creation (see docs/openapi.yaml)'] -->`. Do not invent details.
52 
53### B. Testing & Observability (Mandatory for Each Commit)
54 
551.  **Primary Verification = Automated Tests:** This is the preferred method.
56    - **First Choice: Unit Tests.** Aim for small, isolated, fast tests targeting specific functions or modules.
57    - **Second Choice: Integration Tests.** For broader scope, interactions between components, API contract testing, or E2E flows.
58    - **Fallback (Only if Automated Test is Genuinely Infeasible): Explicit runtime logging or debug output checks.** This must be justified.
59 
602.  **Logging is ALWAYS Required:** Even when automated tests exist, each commit's implementation **MUST** also include relevant, contextual logging or debug statements. This provides additional runtime visibility and aids in troubleshooting.
61    - **Toggleable Logging:** Logging should be configurable (e.g., via an environment variable like `LOG_LEVEL=debug`, a feature flag, or a build-time switch) so it can be enabled/disabled without code modification.
62 
633.  **Structured & Centralized Logs:**
64    - Prefer structured log output (e.g., JSON lines or clear `key="value"` pairs).
65    - Adhere to the project's established logging library and configuration (e.g., `pino`, `winston`). Reference the specific logger configuration file if known (e.g., `src/utils/logger.ts`).
66    - Ensure logs are directed to the project's standard log aggregation system, if applicable.
67 
684.  **Verification Details in Commit Plan (Hierarchy):**
69    - **If Unit Test:** Specify the exact command to run the test(s) (e.g., `pnpm test --filter user-service.test.ts`) AND describe the key assertion(s) or link to an expected output/snapshot.
70    - **If Integration Test:** Specify the exact command or script (e.g., `pnpm test:e2e --spec ./tests/e2e/auth.spec.ts`) AND describe the expected outcome or key behavior being verified.
71    - **If Log Inspection (Fallback):** Detail the precise steps to inspect logs (e.g., `kubectl logs -l app=api-service -c main-container --tail=100 | jq 'select(.msg == "PaymentProcessed")'`) and what specific log message/pattern/value to look for.
72 
73### C. `docs/tasks/<YYYY-MM-DD-HH-MM-task-name>.md` File Structure
74 
75The task file **MUST** be structured as a sequence of planned commits. The primary source for content is the user's task description, **validated, augmented, and detailed** with specific information (file paths, function names, API endpoints, configuration details) extracted from the relevant `docs/` files. **Neglecting to consult and incorporate details from project documentation is a critical failure.**
76 
77Each commit title **MUST** follow semantic commit style (e.g., `feat: ...`, `fix: ...`, `test: ...`, `docs: ...`, `chore: ...`) **and**
78include the task filename in square brackets so each commit can be traced back to
79its plan. Example: `feat: add login API [docs/tasks/2023-10-31-login.md]`.
80 
81```markdown
82# Task: [Brief Task Title - Derived from user request, PRD, or overarching goal]
83 
84## Commit 1: [type: Clear, Descriptive Title for this specific commit]
85**Description:**
86[Explain the precise goal of *this commit*. Include specific file paths (e.g., `src/modules/auth/auth.controller.ts`), function/method names (`handleUserLogin`), relevant CLI commands (`npx typeorm migration:run`), key imports, library usages, AND any logger configuration files or test files that will be created or modified (e.g., `tests/unit/auth.controller.test.ts`, `src/config/logger.config.ts`). Be explicit and detailed.]
87 
88**Verification:**
891.  **Automated Test(s):**
90    *   **Command:** `[Exact command to run the test, e.g., pnpm vitest run src/modules/auth/auth.controller.test.ts]`
91    *   **Expected Outcome:** `[Describe key assertion, e.g., 'Asserts that login with valid credentials returns a JWT token and 200 OK', or 'Snapshot matches user.snapshot']`
922.  **Logging Check:**
93    *   **Action:** `[How to trigger/observe logs, e.g., 'Attempt login via API with invalid credentials']`
94    *   **Expected Log:** `[Specific log message/pattern to verify, e.g., 'INFO: Login attempt failed for user: test@example.com due to InvalidPasswordError']`
95    *   **Toggle Mechanism:** `[How logging is enabled/disabled, e.g., 'LOG_LEVEL=info']`
96 
97---
98 
99## Commit 2: [type: Clear, Descriptive Title for this specific commit]
100**Description:**
101[Details for commit 2...]
102 
103**Verification:**
1041.  **Automated Test(s):**
105    *   **Command:** `[...]`
106    *   **Expected Outcome:** `[...]`
1072.  **Logging Check:**
108    *   **Action:** `[...]`
109    *   **Expected Log:** `[...]`
110    *   **Toggle Mechanism:** `[...]`
111 
112---
113 
114(Repeat structure for up to 5 commits as needed for the task. For simple tasks, you may only need 1-2 commits.)
115 
116```
117 
118## IV. Post Task Plan Creation: Stop and Notify
119 
120 
121Once the *entire content* of the `docs/tasks/<YYYY-MM-DD-HH-MM-task-name>.md` file has been generated (and is your sole output for this rule), **STOP**. Notify the user that the task plan is complete and available at the specified path.
122 
123**Immediately after** providing the file content, output a concise executive summary of all the planned commits so the user can quickly review the steps. This summary should not be part of the task plan file itself.
124 
125After the summary, await the user's next instructions.
126 
127**REMEMBER: Your output is SOLELY the Markdown content of the task plan file. This plan MUST be informed by `docs/` research, detail 2-5 verifiable commits, and rigorously include both automated tests and toggleable logging for each commit. Adhere strictly to the output format and communication constraints.**
128 
129Once the task plan is complete, wait for the user to provide feedback.