task · git:20260408.61db2e8 · 2026-04-08 · sha256 95c31489d2fdc661
task git:20260408.61db2e8A
Immutable. This exact content never changes and is served at /api/v1/blob/95c31489d2fdc661.
---
description: Task execution rules for Glitch Payment Gateway engineering work — verification gates, plan node, self-improvement loop
globs:
alwaysApply: true
---
# Task Execution Rules
These rules apply to **ALL tasks** without exception.
---
## Workflow Orchestration
### Plan Node (Default)
- Treat any non-trivial request (≥3 steps, architectural, or behavioral change) as a planning task.
- Enter plan mode before implementation.
- If new information invalidates the plan, STOP and re-plan immediately.
- Use planning for verification and validation, not only construction.
- Write detailed specs upfront to eliminate ambiguity.
---
## Subagent Strategy
- Decompose complex work aggressively.
- Use subagents for research, exploration, parallel analysis.
- Keep the main context minimal and focused.
- One task per subagent. No multi-purpose agents.
---
## Self-Improvement Loop
- After **any** user correction:
- Update `docs/task/lessons.md`
- Encode a rule preventing the same mistake
- Iterate on lessons ruthlessly until failure rate decreases.
- Review relevant lessons at the start of each session or task.
- **Never skip the lessons update after a correction.**
---
## Verification Before Completion
- Never mark work complete without proof.
- Validate behavior, not intent.
- Diff previous behavior vs new behavior when applicable.
- Ask internally: *"Would a staff-level engineer approve this?"*
- Run tests, inspect logs, and demonstrate correctness explicitly.
### Agent Self-Evaluation Gate (BLOCKING — blocks Visual Verification & User Verification)
After completing implementation, **BEFORE asking the user to test**, you MUST pass this internal gate.
1. **Ask yourself honestly:** *"Is what I implemented the best solution for this problem?"*
2. **Answer truthfully.** Consider:
- Is there a more elegant, maintainable, or performant approach?
- Did I take shortcuts that a staff-level engineer would reject?
- Does the solution fully address the problem, or is it a partial fix?
- Would I be proud to present this implementation in a code review?
- Am I settling for "good enough" when a better solution is within reach?
3. **If the answer is NO** — go back and re-implement using the better approach.
4. **Iterate** — repeat steps 1–3 until the answer is genuinely YES.
5. **You may NOT skip this gate or lie to yourself.**
6. **Only when the answer is honestly YES** may you proceed to the Visual Verification Gate.
### Visual Verification Gate (BLOCKING — blocks User Verification)
After the Self-Evaluation Gate passes, you MUST pass this gate.
1. **Ask yourself:** *"Does this implementation affect the front end, UI, or any visual elements?"*
2. **If the answer is YES:**
a. Open a browser using Chrome MCP tools.
b. Resize to proper dimensions (per `devtools.mdc`).
c. Navigate to every affected page/view/state.
d. Take screenshots of the affected areas.
e. Visually inspect that the implementation renders correctly.
f. **What does NOT count as visual verification:**
- Inspecting raw HTML source code
- DOM analysis or `querySelector` inspection
- Checking template output as text
- Reviewing CSS files without seeing them rendered
- `curl` responses or any text-based/non-visual method
g. **Only a rendered browser screenshot counts.**
h. **If visual verification reveals issues** — fix them, re-run Self-Evaluation Gate, re-verify visually.
3. **If the answer is NO** (purely back-end, CLI, data-only, API-only, config changes) — this gate auto-passes.
4. **If browser tools are unavailable** — report the blocker and do NOT proceed.
### User Verification Gate (BLOCKING — blocks docs & commit cycle)
**Prerequisites:** Self-Evaluation Gate and Visual Verification Gate MUST both have passed.
1. **STOP.** Do not proceed to documentation, task logs, or commit.
2. **Summarize what changed** and what you verified.
3. **If visual verification was performed**, include key findings.
4. **Ask the user to verify:** "Would you like to test this before I proceed with docs and commit?"
5. **Wait for the user's response:**
- **Verify and confirm** → proceed to batch boundary cycle.
- **Report issues** → fix and repeat ALL gates.
- **Explicitly waive** ("continue", "skip verification", "go ahead") → proceed.
6. **Never assume your own checks are sufficient.**
7. **Trivial changes** (typo fixes, comment edits, data-only updates) may skip all three gates.
8. **Scenario Execution Rule (MANDATORY):** You may NOT claim "implementation/testing is complete" unless all required behavior-path scenarios were actually executed end-to-end. **Test Fixture Rule:** If a scenario requires specific data or configuration that no existing entity provides, you MUST create a temporary test fixture. Clean up after.
9. **Automatic Scenario Coverage (MANDATORY):** Execute all materially relevant behavior-path scenarios implied by the implemented change, even if the user does not explicitly list them.
10. **Mandatory Untested List:** In every verification summary, include an explicit `Not Tested` section. If nothing missing: `Not Tested: none.`
### Blocker Protocol (CRITICAL — blocks commit)
- If **any** required verification step cannot be completed, the work is **unverified**.
- **Unverified work MUST NOT be committed or pushed.** Period.
- When blocked:
1. **Try alternate verification methods.**
2. **If no alternative succeeds**, STOP. Do not commit.
3. **Report the blocker clearly** to the user.
4. **Leave changes staged but uncommitted.**
- Never treat "docs updated and automated checks passed" as sufficient when the task plan includes browser/runtime verification that was skipped.
---
## Demand Elegance (Balanced)
- For non-trivial changes: pause and evaluate if a more elegant solution exists.
- If a solution feels hacky: re-implement using the best-known approach.
- Skip elegance checks for simple, obvious fixes.
- Avoid over-engineering.
- Challenge your own output before presenting it.
---
## Autonomous Bug Fixing
- When a bug is reported: fix it directly.
- Identify root causes via logs, errors, and failing tests.
- Resolve without requiring additional user context.
- Fix failing CI/tests proactively.
---
## Task Management Protocol
1. **Plan First** — Write a checklist to `docs/task/todo.md`
2. **Verify Plan** — Confirm direction before implementation
3. **Track Progress** — Mark completed items as work progresses
4. **Explain Changes** — Provide high-level summaries at each step
5. **Log Observations (BLOCKING GATE — at batch boundary)** — Follow `.cursor/rules/agent-observations.mdc`. Append to `docs/agent-observations/`. If none: "Observations: none." **Silence is a violation. Never skip.**
6. **Document Results (at batch boundary)** — Update task log, affected docs. **Do this BEFORE the next task — never defer past a batch boundary.**
7. **Commit & Push (ONLY after explicit user approval)** — Follow `commit.mdc`. USER APPROVAL GATE and VERIFICATION GATE must pass first. Stage with explicit file paths (never `git add -A` or `git add .`). Every completed task gets its own commit.
8. **Capture Lessons** — Update `docs/task/lessons.md` after corrections
---
## CRITICAL: Date-Prefix All Generated Files
Every file you create inside `docs/` subdirectories that are date-scoped **MUST** include a date prefix: `YYYY-MM-DD-{slug}.md`.
### Plan Lifecycle Folders
Plans live in subdirectories of `docs/task/planning/` based on their status:
| Folder | Status | Meaning |
|--------|--------|---------|
| `draft/` | Draft / In Progress | New or unapproved plans, and plans being implemented |
| `pending/` | Pending | Approved but not yet scheduled |
| `completed/` | Complete | Fully implemented, tested, committed |
**Rules:**
- **Always create new plans in `draft/`.** Never in the root plans directory.
- **After marking a plan's status as Complete**, move it to `completed/`.
- **When the user approves but defers**, move to `pending/`.
- **When starting work on a pending plan**, move back to `draft/`.
---
## Core Engineering Principles
- **Simplicity First** — Minimal change, minimal surface area.
- **No Laziness** — Root-cause fixes only. No temporary patches.
- **Minimal Impact** — Touch only what is required.
---
## Enforcement
These rules override all defaults. Never silently bypass these rules.
**GLOBAL NO-SKIP POLICY:** You are never permitted to skip, omit, or work around ANY mandatory rule in this file on your own judgment. If a required step cannot be completed, you MUST stop and report the blocker to the user. Only the user may explicitly waive a rule.