Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# Create a GitHub Issue Task Plan
7 
8 
9**Your Core Task: Generate a multi-commit task plan and post it as a GitHub issue using the `gh` CLI. The issue body must contain the entire plan. No local task file is created.**
10 
11## File Existence Check
12 
13Verify key documentation files before planning:
14 
15```bash
16ls . docs
17```
18 
19Use the results to tailor the task plan.
20 
21## I. Pre-computation: Capture Timestamp
22 
231.  **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"`).
242.  **Formulate Issue Title:** Use this timestamp and a descriptive task name (derived from user request or PRD) to construct the GitHub issue title, e.g., `2023-10-27-14-35 implement user auth`.
25 
26## II. Information Gathering (CRITICAL PRE-REQUISITE)
27 
28- **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.
29- **Prioritized Documents:** Pay special attention to (if they exist):
30    - `docs/PRD.md` (Product Requirements Document)
31    - `docs/TECH_STACK.md`
32    - `docs/openapi.yaml` (or similar API specifications)
33    - `docs/logging.md`, `docs/LOGGING_GUIDE.md` (or any docs related to logging practices)
34    - `docs/TEST_STRATEGY.md`, `docs/TESTING_GUIDELINES.md` (or any docs related to testing)
35    - `NOTES.md` (if present at project root or in `docs/`)
36- **Purpose:** This information is *essential* for creating an accurate, relevant, and genuinely useful task plan that aligns with project standards.
37 
38## III. Core Directive: Construct the Task Plan File
39 
40Create the issue body content. This body 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.
41 
42### A. Strict Operational Constraints
43 
44- **File Operations:**
45    - **No Local Files:** Do NOT create any local task file. The entire plan will be posted as a GitHub issue via `gh issue create`.
46    - Reading project documentation from `docs/` (as specified above) is **MANDATORY** to inform the plan.
47- **Communication Protocol:**
48    - **NO Conversational Output:** You are forbidden from generating any conversational output, commentary, preamble, or summaries *before* or *during* creation of the issue body.
49    - **Output is the Issue Body Content:** Your *entire* output for this specific rule invocation must be *only* the complete, raw Markdown content that will become the GitHub issue body.
50- **User Interaction:**
51    - You receive the initial task description from the user.
52    - 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.
53 
54### B. Testing & Observability (Mandatory for Each Commit)
55 
561.  **Primary Verification = Automated Tests:** This is the preferred method.
57    - **First Choice: Unit Tests.** Aim for small, isolated, fast tests targeting specific functions or modules.
58    - **Second Choice: Integration Tests.** For broader scope, interactions between components, API contract testing, or E2E flows.
59    - **Fallback (Only if Automated Test is Genuinely Infeasible): Explicit runtime logging or debug output checks.** This must be justified.
60 
612.  **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.
62    - **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.
63 
643.  **Structured & Centralized Logs:**
65    - Prefer structured log output (e.g., JSON lines or clear `key="value"` pairs).
66    - 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`).
67    - Ensure logs are directed to the project's standard log aggregation system, if applicable.
68 
694.  **Verification Details in Commit Plan (Hierarchy):**
70    - **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.
71    - **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.
72    - **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.
73 
74### Issue Body Structure
75 
76The issue body **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.**
77 
78Each commit title **MUST** follow semantic commit style (e.g., `feat: ...`, `fix: ...`, `test: ...`, `docs: ...`, `chore: ...`) **and**
79include the GitHub issue number in parentheses for traceability. Example:
80`feat: add login API (#42)`.
81 
82```markdown
83# Task: [Brief Task Title - Derived from user request, PRD, or overarching goal]
84 
85## Commit 1: [type: Clear, Descriptive Title for this specific commit]
86**Description:**
87[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.]
88 
89**Verification:**
901.  **Automated Test(s):**
91    *   **Command:** `[Exact command to run the test, e.g., pnpm vitest run src/modules/auth/auth.controller.test.ts]`
92    *   **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']`
932.  **Logging Check:**
94    *   **Action:** `[How to trigger/observe logs, e.g., 'Attempt login via API with invalid credentials']`
95    *   **Expected Log:** `[Specific log message/pattern to verify, e.g., 'INFO: Login attempt failed for user: test@example.com due to InvalidPasswordError']`
96    *   **Toggle Mechanism:** `[How logging is enabled/disabled, e.g., 'LOG_LEVEL=info']`
97 
98---
99 
100## Commit 2: [type: Clear, Descriptive Title for this specific commit]
101**Description:**
102[Details for commit 2...]
103 
104**Verification:**
1051.  **Automated Test(s):**
106    *   **Command:** `[...]`
107    *   **Expected Outcome:** `[...]`
1082.  **Logging Check:**
109    *   **Action:** `[...]`
110    *   **Expected Log:** `[...]`
111    *   **Toggle Mechanism:** `[...]`
112 
113---
114 
115(Repeat structure for up to 5 commits as needed for the task. For simple tasks, you may only need 1-2 commits.)
116 
117```
118 
119## IV. Post Task Plan Creation: Stop and Notify
120 
121After posting the issue with the complete body via `gh issue create`, **STOP**. Notify the user of the newly created issue number or URL.
122 
123**Immediately after** posting, provide a short executive summary of the planned commits so the user can quickly review the steps. This summary must not be part of the issue body itself.
124 
125After delivering the summary, await the user's next instructions.
126 
127**REMEMBER: Your output is SOLELY the Markdown content of the issue body. 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.
130