feat(skills): improve skills with pipeline enforcement and skill delegation (#510)
This commit is contained in:
Carlos Florêncio
+55
-8
@@ -12,16 +12,37 @@ Verify that a feature works as intended after implementation. Assume bugs exist
|
||||
|
||||
Mindset: you are not confirming it works — you are discovering where it breaks.
|
||||
|
||||
## Steps
|
||||
## Before starting: create the pipeline
|
||||
|
||||
### 1. Understand the intent
|
||||
Create these tasks immediately (use your task/todo tracking tool if available):
|
||||
|
||||
1. **Understand the intent** — Read task/PR/commits to understand what was built
|
||||
2. **Trace the wiring** — Verify the feature is actually connected end-to-end
|
||||
3. **Test the happy path** — Run the feature as a user would
|
||||
4. **Try to break it** — Boundary values, error paths, concurrency, auth
|
||||
5. **Verify test coverage** — Check for missing tests, write them if needed
|
||||
6. **Report** — Summarize findings with verdict
|
||||
|
||||
Mark each task in_progress when you begin it and completed when you finish it. Do not skip phases — tracing the wiring before testing catches disconnected code early, and testing the happy path before edge cases establishes a working baseline.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Understand the intent
|
||||
|
||||
Mark task 1 as in_progress.
|
||||
|
||||
Read the task description, PR, or recent commits to understand what was built and what it should do. Identify:
|
||||
- The expected behavior (happy path)
|
||||
- System boundaries (user input, API endpoints, external data)
|
||||
- Integration points (what calls what, data flow end-to-end)
|
||||
|
||||
### 2. Trace the wiring
|
||||
Mark task 1 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Trace the wiring
|
||||
|
||||
Mark task 2 as in_progress.
|
||||
|
||||
Before testing behavior, verify the feature is actually connected:
|
||||
- Exports are imported and used (not just defined)
|
||||
@@ -31,14 +52,26 @@ Before testing behavior, verify the feature is actually connected:
|
||||
|
||||
If something is orphaned or unwired, stop and report it — no point testing disconnected code.
|
||||
|
||||
### 3. Test the happy path
|
||||
Mark task 2 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Test the happy path
|
||||
|
||||
Mark task 3 as in_progress.
|
||||
|
||||
Run the feature as a user would. For backend changes, call the API. For frontend changes, trace the UI flow. For both, follow the full path:
|
||||
- Does the basic use case work?
|
||||
- Does the response/output match expectations?
|
||||
- Is the data persisted correctly?
|
||||
|
||||
### 4. Try to break it
|
||||
Mark task 3 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Try to break it
|
||||
|
||||
Mark task 4 as in_progress.
|
||||
|
||||
Systematically test these categories (skip what doesn't apply):
|
||||
|
||||
@@ -61,14 +94,26 @@ Systematically test these categories (skip what doesn't apply):
|
||||
- Can the feature be accessed without proper auth?
|
||||
- Does it respect permission boundaries?
|
||||
|
||||
### 5. Verify test coverage
|
||||
Mark task 4 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Verify test coverage
|
||||
|
||||
Mark task 5 as in_progress.
|
||||
|
||||
Check that the implementation has tests covering the behaviors you just verified:
|
||||
- Are the happy path and key error paths tested?
|
||||
- Are edge cases from step 4 covered?
|
||||
- Are edge cases from Phase 4 covered?
|
||||
- If tests are missing, write them following TDD (write failing test first, then verify it passes with existing code)
|
||||
|
||||
### 6. Report
|
||||
Mark task 5 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Report
|
||||
|
||||
Mark task 6 as in_progress.
|
||||
|
||||
Summarize what was tested and what was found:
|
||||
|
||||
@@ -82,3 +127,5 @@ Summarize what was tested and what was found:
|
||||
- Behaviors that work but have no automated test
|
||||
|
||||
**Verdict:** Feature complete / Has issues — fix before merge
|
||||
|
||||
Mark task 6 as completed.
|
||||
|
||||
@@ -7,6 +7,10 @@ description: Review changed code for quality, security, and architecture complia
|
||||
|
||||
Review the current changes in the codebase (Go + Next.js monorepo). Every finding needs a `file_path:line_number` reference, an explanation of *why* it matters, and a concrete fix.
|
||||
|
||||
## Available skills
|
||||
|
||||
- **`/tdd`** — Recommend when flagging untested logic. The author can use this to add tests.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Identify changed files and check scope
|
||||
|
||||
@@ -7,6 +7,10 @@ description: Stage and commit changes using Conventional Commits. Use when there
|
||||
|
||||
Create a git commit following this project's Conventional Commits convention. These messages are used by git-cliff (`cliff.toml`) to auto-generate changelogs and release notes. PRs are squash-merged, so the PR title becomes the commit on `main` — CI validates it via `pr-title.yml`.
|
||||
|
||||
## Available skills and subagents
|
||||
|
||||
- **`verify` subagent** — Run fmt, typecheck, test, and lint. Delegate to this before committing to catch issues early.
|
||||
|
||||
## Format
|
||||
|
||||
```
|
||||
@@ -46,11 +50,11 @@ ci: add PR title linting workflow
|
||||
|
||||
## Steps
|
||||
|
||||
**Create a todo/task for each step below and mark them as completed as you go.**
|
||||
**Create a task for each step below and mark them as completed as you go.**
|
||||
|
||||
1. Run `git status` and `git diff` to understand all changes
|
||||
2. Review recent commits with `git log --oneline -10` to match project style
|
||||
3. Delegate to the **`verify` sub-agent** to run the full verification pipeline (rebase, format, typecheck, test, lint). It will fix any issues it finds. Wait for it to complete before proceeding.
|
||||
3. Delegate to the `verify` subagent to run the full verification pipeline (rebase, format, typecheck, test, lint). It will fix any issues it finds. Wait for it to complete before proceeding.
|
||||
4. Stage relevant files (prefer specific files over `git add -A`)
|
||||
5. Write a commit message following the format above
|
||||
6. If changes span multiple concerns, consider separate commits
|
||||
|
||||
@@ -5,9 +5,16 @@ description: Write and run web E2E tests (Playwright) using TDD — locations, p
|
||||
|
||||
# E2E Tests
|
||||
|
||||
Write E2E tests using `/tdd` (Red-Green-Refactor). Always run the tests you create and watch them fail before implementing.
|
||||
Write E2E tests using TDD (Red-Green-Refactor). Always run the tests you create and watch them fail before implementing.
|
||||
|
||||
**Location:** `apps/web/e2e/`
|
||||
## Available skills and subagents
|
||||
|
||||
- **`/tdd`** — Follow the Red-Green-Refactor cycle when writing tests.
|
||||
- **`/verify`** — Run after completing tests to ensure everything passes across the monorepo.
|
||||
|
||||
## Location
|
||||
|
||||
`apps/web/e2e/`
|
||||
|
||||
```
|
||||
apps/web/e2e/
|
||||
|
||||
@@ -7,27 +7,69 @@ description: Guided feature development — brainstorm, explore codebase, design
|
||||
|
||||
Systematic feature development: understand the problem, explore the codebase, design the solution, implement with TDD, verify it works, and review.
|
||||
|
||||
**No implementation before design approval.**
|
||||
## Available skills and subagents
|
||||
|
||||
The following skills and subagents are available in this repo to delegate work to. Use them instead of doing everything inline — they have specialized instructions and keep your context clean:
|
||||
|
||||
- **`/tdd`** — Implement changes using Test-Driven Development (Red-Green-Refactor). Delegate implementation tasks to this.
|
||||
- **`/e2e`** — Write and run Playwright E2E tests using TDD. Use for the final wave when the full feature needs end-to-end coverage.
|
||||
- **`qa` subagent** — Verify a feature works after implementation. Actively tries to break it — edge cases, error paths, integration wiring.
|
||||
- **`verify` subagent** — Run fmt, typecheck, test, and lint across the monorepo, then fix any issues found.
|
||||
- **`simplify` subagent** — Simplify recently changed code — inline one-off abstractions, remove speculative code, reduce nesting.
|
||||
- **`code-review` subagent** — Review changed code for quality, security, and architecture compliance.
|
||||
|
||||
---
|
||||
|
||||
## Before anything else: create the pipeline
|
||||
|
||||
The first thing you do — before reading code, before asking questions, before any exploration — is create a task list for the full pipeline. This is non-negotiable because it keeps you accountable to the process and lets the user see where you are.
|
||||
|
||||
Create these tasks immediately (use your task/todo tracking tool if available):
|
||||
|
||||
1. **Understand the problem** — Clarify requirements, identify constraints, confirm understanding with user
|
||||
2. **Explore the codebase** — Find similar patterns, relevant architecture, integration points
|
||||
3. **Design the solution** — Propose approaches with trade-offs, get user approval before implementing
|
||||
4. **Implement with TDD** — Break into waves, implement test-first, delegate where possible
|
||||
5. **QA** — Verify the feature works end-to-end, try to break it
|
||||
6. **Review and finalize** — Simplify, verify, code review, summarize
|
||||
|
||||
Then start with task 1. Mark each task in_progress when you begin it and completed when you finish it. Do not skip ahead — each phase produces context that the next phase needs. Designing without exploring leads to solutions that fight the codebase. Implementing without design approval wastes time on the wrong approach.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Understand the problem
|
||||
|
||||
Mark task 1 as in_progress.
|
||||
|
||||
1. If the request is vague, ask clarifying questions — one at a time, prefer multiple choice
|
||||
2. Challenge the premise: is this the right feature, or is the real need something different?
|
||||
2. **Challenge the premise** — before accepting the feature at face value, ask whether this is the right solution to the underlying problem. For example: "Have you considered X instead?" or "Is the real need Y rather than Z?" This is especially important for vague requests where the user may not have thought through alternatives. Even for clear requests, briefly consider whether a simpler approach exists.
|
||||
3. Identify: what problem is being solved, who benefits, what are the constraints
|
||||
4. Summarize understanding and confirm with the user
|
||||
|
||||
Mark task 1 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Explore the codebase
|
||||
|
||||
1. Launch 2-3 Explore agents in parallel targeting different aspects:
|
||||
Mark task 2 as in_progress.
|
||||
|
||||
1. Search the codebase in parallel targeting different aspects:
|
||||
- Similar features and their implementation patterns
|
||||
- Architecture and abstractions in the relevant area
|
||||
- Integration points, data flow, and extension points
|
||||
2. Read all key files the agents identify
|
||||
2. Read all key files identified
|
||||
3. Check `docs/decisions/INDEX.md` for relevant architectural decisions in this area
|
||||
4. Present a summary of existing patterns and conventions to reuse
|
||||
|
||||
Mark task 2 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Design
|
||||
|
||||
Mark task 3 as in_progress.
|
||||
|
||||
1. **Scope check:** If the feature spans multiple independent subsystems, break it into sub-features first. Each should produce working, testable software on its own.
|
||||
2. Identify remaining ambiguities: edge cases, error handling, scope boundaries, backward compatibility
|
||||
3. Ask the user to resolve them — do not assume
|
||||
@@ -35,51 +77,56 @@ Systematic feature development: understand the problem, explore the codebase, de
|
||||
- Minimal change (smallest diff, maximum reuse)
|
||||
- Clean architecture (maintainability, elegant abstractions)
|
||||
- Pragmatic balance (speed + quality)
|
||||
5. **Map the file structure:** Before getting approval, list which files will be created or modified and what each is responsible for. This locks in decomposition decisions.
|
||||
6. Get explicit user approval on the approach before proceeding
|
||||
5. **Map the file structure:** List which files will be created or modified and what each is responsible for. This locks in decomposition decisions.
|
||||
6. **Stop and wait for explicit user approval on the approach before proceeding.** Do not start Phase 4 until the user confirms the design.
|
||||
|
||||
Mark task 3 as completed only after the user approves.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Implement with TDD
|
||||
|
||||
**You are the coordinator.** Your job is to hold the big picture (requirements, design, file structure, wave progress) and delegate implementation to subagents. Protect your context:
|
||||
Mark task 4 as in_progress.
|
||||
|
||||
- **Prefer subagents over inline work.** Every task you implement inline fills your context with code details and tool outputs. Delegate to subagents whenever possible — they get fresh context and return only a summary.
|
||||
- **Keep coupled tasks small.** If you must implement inline (coupled tasks), keep each task focused and short. Don't read entire files unnecessarily — read only what you need to verify the subagent's work or wire things together.
|
||||
- **Don't debug in the coordinator.** If a subagent's task fails quality gates, dispatch a new subagent to fix it rather than debugging inline. Pass the failure details and let the fresh subagent investigate.
|
||||
**You are the coordinator.** Your job is to hold the big picture (requirements, design, file structure, wave progress) and delegate implementation. Protect your context:
|
||||
|
||||
- **Delegate over inline work.** Every task you implement inline fills your context with code details and tool outputs. Delegate to sub-tasks whenever possible — they get fresh context and return only a summary.
|
||||
- **Keep coupled tasks small.** If you must implement inline (coupled tasks), keep each task focused and short. Don't read entire files unnecessarily — read only what you need to verify work or wire things together.
|
||||
- **Don't debug in the coordinator.** If a task fails quality gates, dispatch a new sub-task to fix it rather than debugging inline. Pass the failure details and let the fresh context investigate.
|
||||
- **Track progress, not details.** For each completed task, note: what was done, which files changed, commit hash. Don't carry the implementation details forward.
|
||||
|
||||
### 4a. Decompose into tasks
|
||||
### 4a. Decompose into implementation tasks
|
||||
|
||||
Using the file structure map from Phase 3, break the implementation into discrete tasks. Each task should:
|
||||
Using the file structure map from Phase 3, create sub-tasks for each discrete piece of work. Each task should:
|
||||
- Touch a specific set of files
|
||||
- Have a clear done condition (test passes, API works, component renders)
|
||||
- Be classifiable as independent or coupled
|
||||
|
||||
### 4b. Group into waves
|
||||
|
||||
Subagents share the same worktree, so parallelism is constrained by build boundaries:
|
||||
- **Backend (Go)**: packages compile independently — different packages can run in parallel subagents
|
||||
- **Frontend (Next.js)**: single build — only ONE subagent can work on frontend at a time
|
||||
Parallelism is constrained by build boundaries:
|
||||
- **Backend (Go)**: packages compile independently — different packages can run in parallel
|
||||
- **Frontend (Next.js)**: single build — only ONE task can work on frontend at a time
|
||||
- **E2E tests**: need full build — only after both backend and frontend changes are done
|
||||
- **Coupled tasks** (shared types, sequential data flow): must run sequentially regardless
|
||||
|
||||
Group tasks into waves. Example:
|
||||
```text
|
||||
Wave 1 (parallel): [Backend API handler (subagent), Frontend component + hook (subagent)]
|
||||
Wave 1 (parallel): [Backend API handler, Frontend component + hook]
|
||||
Wave 2 (sequential): [Wire frontend to API, integration test]
|
||||
Wave 3: [E2E test for the full flow]
|
||||
```
|
||||
|
||||
Max parallelism: 1 frontend subagent + 1-2 backend subagents (if working on independent packages). For small features with 1-3 tasks, skip wave grouping and implement sequentially.
|
||||
For small features with 1-3 tasks, skip wave grouping and implement sequentially.
|
||||
|
||||
### 4c. Execute wave by wave
|
||||
|
||||
For each wave, follow `/tdd` strictly (RED-GREEN-REFACTOR):
|
||||
For each wave, follow TDD strictly (RED-GREEN-REFACTOR):
|
||||
|
||||
**Independent tasks in the wave**: dispatch one subagent per task. Each gets fresh context with:
|
||||
**Independent tasks in the wave**: delegate each task via `/tdd`. Each gets:
|
||||
- Task description and acceptance criteria
|
||||
- Relevant file paths from Phase 3
|
||||
- Codebase conventions from Phase 2
|
||||
- Instruction to follow `/tdd`
|
||||
|
||||
**Coupled tasks** (e.g., wiring frontend to backend, integration glue): implement inline but keep it minimal — only the glue code, not full feature implementation.
|
||||
|
||||
@@ -91,29 +138,45 @@ After each wave completes:
|
||||
- Backend: `cd apps/backend && go test ./internal/path/...` (changed packages only)
|
||||
- Frontend: `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web test`
|
||||
- If tests fail, fix before proceeding to the next wave
|
||||
- E2E tests only in the final wave or Phase 5 (QA)
|
||||
- E2E tests only in the final wave (via `/e2e`) or Phase 5 (QA)
|
||||
|
||||
Mark each implementation sub-task as completed as it passes its quality gate.
|
||||
|
||||
### 4e. Stop conditions
|
||||
|
||||
- **Bugs or missing validation discovered during a subagent's task:** the subagent fixes it inline. If the bug surfaces after a wave completes (quality gate failure), dispatch a new subagent to fix it — don't debug in the coordinator.
|
||||
- **Bugs or missing validation discovered during a task:** fix inline. If the bug surfaces after a wave completes (quality gate failure), dispatch a new task to fix it — don't debug in the coordinator.
|
||||
- **Blocker (missing dependency, unclear requirement, test fails repeatedly):** stop and ask the user
|
||||
- **Fix requires architectural change (new DB table, new service layer, switching libraries):** stop and ask — don't make structural decisions silently
|
||||
- **3 failed fix attempts on the same issue:** stop, question the approach, ask the user
|
||||
|
||||
Mark task 4 as completed when all implementation sub-tasks pass their quality gates.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: QA
|
||||
|
||||
Delegate to the **`qa` sub-agent** to verify the feature works end-to-end. It will:
|
||||
Mark task 5 as in_progress.
|
||||
|
||||
Delegate to the `qa` subagent to verify the feature works end-to-end. It will:
|
||||
- Trace the wiring (exports used, APIs called, data flows)
|
||||
- Test the happy path
|
||||
- Try to break it (boundary values, error paths, concurrency)
|
||||
- Write tests for any gaps found
|
||||
|
||||
## Phase 6: Review
|
||||
Mark task 5 as completed.
|
||||
|
||||
1. Delegate to the **`simplify` sub-agent** to clean up the implementation
|
||||
2. Delegate to the **`verify` sub-agent** to ensure fmt, typecheck, test, and lint all pass
|
||||
3. Delegate to the **`code-review` sub-agent** to review the changes
|
||||
---
|
||||
|
||||
## Phase 6: Review and finalize
|
||||
|
||||
Mark task 6 as in_progress.
|
||||
|
||||
1. Delegate to the `simplify` subagent to clean up the implementation
|
||||
2. Delegate to the `verify` subagent to run fmt, typecheck, test, and lint
|
||||
3. Delegate to the `code-review` subagent to review changes for quality, security, and architecture compliance
|
||||
4. Fix any blockers, present suggestions to the user
|
||||
5. Summarize: what was built, key decisions, files modified, suggested next steps
|
||||
6. If significant architectural decisions were made, record them via `/record decision`
|
||||
7. Save the feature design to `docs/plans/` via `/record plan` for permanent reference
|
||||
6. If significant architectural decisions were made, record them
|
||||
7. Save the feature design to `docs/plans/` for permanent reference
|
||||
|
||||
Mark task 6 as completed.
|
||||
|
||||
+54
-13
@@ -5,11 +5,32 @@ description: Fix bugs and issues — reproduce, find root cause, minimal fix wit
|
||||
|
||||
# Fix
|
||||
|
||||
Systematic bug fixing: reproduce the problem, find the root cause, apply a minimal fix with a regression test. **No fix without root cause investigation first.**
|
||||
Systematic bug fixing: reproduce the problem, find the root cause, apply a minimal fix with a regression test.
|
||||
|
||||
## Steps
|
||||
## Available skills and subagents
|
||||
|
||||
### 1. Reproduce
|
||||
- **`/tdd`** — Use for implementing the fix with a regression test (Red-Green-Refactor).
|
||||
- **`/e2e`** — Use when the bug is in a user-facing flow and needs a Playwright regression test.
|
||||
- **`/verify`** — Run after fixing to ensure nothing else broke.
|
||||
|
||||
---
|
||||
|
||||
## Before anything else: create the pipeline
|
||||
|
||||
Create these tasks immediately (use your task/todo tracking tool if available):
|
||||
|
||||
1. **Reproduce the bug** — Write a test or find a reliable reproduction case
|
||||
2. **Find the root cause** — Trace the code path, narrow the scope, state the cause clearly
|
||||
3. **Fix with TDD** — Minimal fix with regression test, no surrounding refactors
|
||||
4. **Verify** — Run full verification, check for similar patterns elsewhere
|
||||
|
||||
Then start with task 1. Mark each task in_progress when you begin it and completed when you finish it. Do not skip ahead — fixing without reproducing leads to patches that don't address the real problem. Fixing without understanding the root cause leads to whack-a-mole.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Reproduce
|
||||
|
||||
Mark task 1 as in_progress.
|
||||
|
||||
Before anything else, reproduce the bug reliably. Pick the right method based on where the bug lives:
|
||||
|
||||
@@ -21,7 +42,13 @@ Before anything else, reproduce the bug reliably. Pick the right method based on
|
||||
If it can't be reproduced, add logging/assertions to gather more info — don't guess at a fix.
|
||||
Find the minimal reproduction case: strip away everything that isn't needed to trigger the bug.
|
||||
|
||||
### 2. Narrow down the cause
|
||||
Mark task 1 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Find the root cause
|
||||
|
||||
Mark task 2 as in_progress.
|
||||
|
||||
Don't guess and patch — systematically narrow the scope:
|
||||
|
||||
@@ -31,27 +58,41 @@ Don't guess and patch — systematically narrow the scope:
|
||||
|
||||
**Check history (only if it used to work):** If a feature regressed, use `git bisect` to find the commit that broke it. Skip this for bugs that were always present.
|
||||
|
||||
### 3. Confirm root cause
|
||||
|
||||
Before fixing, state the root cause clearly:
|
||||
**Before proceeding, state the root cause clearly:**
|
||||
- What is the actual cause (not the symptom)?
|
||||
- Why does it happen? (e.g., "empty string bypasses validation and reaches the DB layer")
|
||||
- Under what conditions? (e.g., "only when the input is whitespace-only")
|
||||
|
||||
If you can't state this clearly, you haven't found the root cause yet — go back to step 2.
|
||||
If you can't state this clearly, you haven't found the root cause yet — keep investigating. Present your root cause analysis to the user before fixing.
|
||||
|
||||
### 4. Fix with TDD
|
||||
Mark task 2 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Fix with TDD
|
||||
|
||||
Mark task 3 as in_progress.
|
||||
|
||||
Follow `/tdd`:
|
||||
1. Write a test that reproduces the exact bug — confirm it fails
|
||||
2. Write the minimal fix — change only what's necessary, don't refactor surrounding code
|
||||
3. Confirm the test passes and no other tests regress
|
||||
|
||||
### 5. Verify
|
||||
Mark task 3 as completed.
|
||||
|
||||
- Run `/verify` to ensure nothing else broke
|
||||
- Check that the fix addresses the root cause, not just the symptom
|
||||
- If the same category of bug could occur elsewhere, grep for similar patterns
|
||||
---
|
||||
|
||||
## Phase 4: Verify
|
||||
|
||||
Mark task 4 as in_progress.
|
||||
|
||||
1. Run `/verify` to ensure nothing else broke
|
||||
2. Check that the fix addresses the root cause, not just the symptom
|
||||
3. If the same category of bug could occur elsewhere, grep for similar patterns and flag them
|
||||
|
||||
Mark task 4 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Stop conditions
|
||||
|
||||
|
||||
@@ -7,6 +7,11 @@ description: Wait for CI checks and automated reviews (CodeRabbit, Greptile) on
|
||||
|
||||
Wait for CI and code review to complete on a pull request, fix any failures or valid comments, then push.
|
||||
|
||||
## Available skills and subagents
|
||||
|
||||
- **`verify` subagent** — Run the full verification pipeline (format, typecheck, test, lint) before pushing fixes.
|
||||
- **`/commit`** — Use for staging and committing fixes with Conventional Commits format.
|
||||
|
||||
## Context
|
||||
|
||||
- Current branch: !`git branch --show-current`
|
||||
|
||||
@@ -5,6 +5,11 @@ description: Commit, push, and create a PR. Default is ready-for-review with aut
|
||||
|
||||
# PR
|
||||
|
||||
## Available skills
|
||||
|
||||
- **`/commit`** — Stage and commit changes using Conventional Commits. Runs `/verify` internally.
|
||||
- **`/pr-fixup`** — Wait for CI checks and CodeRabbit review, fix any failures or valid comments, and push.
|
||||
|
||||
## Context
|
||||
|
||||
- Current git status: !`git status`
|
||||
@@ -17,13 +22,9 @@ description: Commit, push, and create a PR. Default is ready-for-review with aut
|
||||
- `--draft` — create the PR as draft and skip the fixup step. Use when the work is not ready for review.
|
||||
- Default (no flag) — create as ready-for-review and run `/pr-fixup` to wait for CI/CodeRabbit and fix issues.
|
||||
|
||||
## Your task
|
||||
## Steps
|
||||
|
||||
Commit, push, and create a pull request.
|
||||
|
||||
### Steps
|
||||
|
||||
**Create a todo/task for each step below and mark them as completed as you go.**
|
||||
**Create a task for each step below and mark them as completed as you go.**
|
||||
|
||||
1. **Uncommitted changes:** If there are dirty or staged changes, run `/commit` first (it runs `/verify` internally).
|
||||
|
||||
@@ -36,7 +37,7 @@ Commit, push, and create a pull request.
|
||||
**PR title** must follow Conventional Commits format (see `/commit` for full rules). CI validates via `pr-title.yml` — the PR title becomes the squash-merge commit used for release notes.
|
||||
|
||||
**PR body** must follow the project's pull request template:
|
||||
- **Summary** (required): 1–2 sentences of prose, no heading. Lead with the problem/goal, end with the outcome. Say WHY, not what.
|
||||
- **Summary** (required): 1-2 sentences of prose, no heading. Lead with the problem/goal, end with the outcome. Say WHY, not what.
|
||||
- **Important Changes** (optional): short bullet list of significant architectural changes. Remove section if not needed.
|
||||
- **Validation** (required): list commands or checks run (e.g. `go test ./...`, `make lint`).
|
||||
- **Diagram** (optional): Mermaid diagram only for non-obvious flows. Remove section if not needed.
|
||||
|
||||
@@ -5,6 +5,11 @@ description: Commit and push to the current branch. Use --fixup to also wait for
|
||||
|
||||
# Push
|
||||
|
||||
## Available skills
|
||||
|
||||
- **`/commit`** — Stage and commit changes using Conventional Commits. Runs `/verify` internally.
|
||||
- **`/pr-fixup`** — Wait for CI checks and CodeRabbit review, fix any failures, and push again.
|
||||
|
||||
## Context
|
||||
|
||||
- Current branch: !`git branch --show-current`
|
||||
|
||||
@@ -9,16 +9,44 @@ Verify that a feature works as intended after implementation. Assume bugs exist
|
||||
|
||||
Mindset: you are not confirming it works — you are discovering where it breaks.
|
||||
|
||||
## Steps
|
||||
## Available skills
|
||||
|
||||
### 1. Understand the intent
|
||||
- **`/tdd`** — Use to write tests for any gaps found during QA.
|
||||
- **`/e2e`** — Use to write Playwright E2E tests for user-facing flows that lack coverage.
|
||||
|
||||
---
|
||||
|
||||
## Before starting: create the pipeline
|
||||
|
||||
Create these tasks immediately (use your task/todo tracking tool if available):
|
||||
|
||||
1. **Understand the intent** — Read task/PR/commits to understand what was built
|
||||
2. **Trace the wiring** — Verify the feature is actually connected end-to-end
|
||||
3. **Test the happy path** — Run the feature as a user would
|
||||
4. **Try to break it** — Boundary values, error paths, concurrency, auth
|
||||
5. **Verify test coverage** — Check for missing tests, write them if needed
|
||||
6. **Report** — Summarize findings with verdict
|
||||
|
||||
Mark each task in_progress when you begin it and completed when you finish it.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Understand the intent
|
||||
|
||||
Mark task 1 as in_progress.
|
||||
|
||||
Read the task description, PR, or recent commits to understand what was built and what it should do. Identify:
|
||||
- The expected behavior (happy path)
|
||||
- System boundaries (user input, API endpoints, external data)
|
||||
- Integration points (what calls what, data flow end-to-end)
|
||||
|
||||
### 2. Trace the wiring
|
||||
Mark task 1 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Trace the wiring
|
||||
|
||||
Mark task 2 as in_progress.
|
||||
|
||||
Before testing behavior, verify the feature is actually connected:
|
||||
- Exports are imported and used (not just defined)
|
||||
@@ -28,14 +56,26 @@ Before testing behavior, verify the feature is actually connected:
|
||||
|
||||
If something is orphaned or unwired, stop and report it — no point testing disconnected code.
|
||||
|
||||
### 3. Test the happy path
|
||||
Mark task 2 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Test the happy path
|
||||
|
||||
Mark task 3 as in_progress.
|
||||
|
||||
Run the feature as a user would. For backend changes, call the API. For frontend changes, trace the UI flow. For both, follow the full path:
|
||||
- Does the basic use case work?
|
||||
- Does the response/output match expectations?
|
||||
- Is the data persisted correctly?
|
||||
|
||||
### 4. Try to break it
|
||||
Mark task 3 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Try to break it
|
||||
|
||||
Mark task 4 as in_progress.
|
||||
|
||||
Systematically test these categories (skip what doesn't apply):
|
||||
|
||||
@@ -58,14 +98,26 @@ Systematically test these categories (skip what doesn't apply):
|
||||
- Can the feature be accessed without proper auth?
|
||||
- Does it respect permission boundaries?
|
||||
|
||||
### 5. Verify test coverage
|
||||
Mark task 4 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Verify test coverage
|
||||
|
||||
Mark task 5 as in_progress.
|
||||
|
||||
Check that the implementation has tests covering the behaviors you just verified:
|
||||
- Are the happy path and key error paths tested?
|
||||
- Are edge cases from step 4 covered?
|
||||
- If tests are missing, write them using `/tdd`
|
||||
- Are edge cases from Phase 4 covered?
|
||||
- If tests are missing, write them using `/tdd` (or `/e2e` for user-facing flows)
|
||||
|
||||
### 6. Report
|
||||
Mark task 5 as completed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Report
|
||||
|
||||
Mark task 6 as in_progress.
|
||||
|
||||
Summarize what was tested and what was found:
|
||||
|
||||
@@ -79,3 +131,5 @@ Summarize what was tested and what was found:
|
||||
- Behaviors that work but have no automated test
|
||||
|
||||
**Verdict:** Feature complete / Has issues — fix before merge
|
||||
|
||||
Mark task 6 as completed.
|
||||
|
||||
@@ -9,6 +9,10 @@ Post-implementation simplification pass. Review recently changed code and active
|
||||
|
||||
The best code is code you don't have to write. The second best is code anyone can read.
|
||||
|
||||
## Available skills and subagents
|
||||
|
||||
- **`verify` subagent** — Run after simplifications to ensure all tests, lints, and typechecks still pass.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Identify what to simplify
|
||||
|
||||
@@ -9,6 +9,11 @@ Implement code changes using strict Red-Green-Refactor. Iron law: **no productio
|
||||
|
||||
Wrote code before a test? Delete it. Start over from a failing test.
|
||||
|
||||
## Available skills and subagents
|
||||
|
||||
- **`/e2e`** — Use when the change needs a Playwright E2E test instead of a unit test.
|
||||
- **`/verify`** — Run after completing all TDD cycles to ensure everything passes across the monorepo.
|
||||
|
||||
## When to use
|
||||
|
||||
- Bug fixes — write a test that reproduces the bug before fixing
|
||||
@@ -27,14 +32,9 @@ Wrote code before a test? Delete it. Start over from a failing test.
|
||||
```bash
|
||||
cd apps && pnpm --filter @kandev/web test -- --run path/to/file.test.ts
|
||||
```
|
||||
- **Web E2E** (`apps/web/e2e/`): Playwright tests with full-stack isolation (backend + frontend + DB per worker). Uses page objects in `e2e/pages/` and fixtures in `e2e/fixtures/`. Run:
|
||||
```bash
|
||||
make test-e2e # all tests, headless
|
||||
cd apps && pnpm --filter @kandev/web e2e -- tests/my-test.spec.ts # single file
|
||||
make test-e2e-headed # with visible browser
|
||||
```
|
||||
- **Web E2E** (`apps/web/e2e/`): delegate to `/e2e` for Playwright tests.
|
||||
|
||||
Choose the right level: unit tests for isolated logic, web E2E for user-facing flows.
|
||||
Choose the right level: unit tests for isolated logic, E2E for user-facing flows.
|
||||
|
||||
## Steps
|
||||
|
||||
|
||||
@@ -9,45 +9,64 @@ Run the full verification pipeline for the monorepo, then fix any issues found.
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Rebase on main** (ensures CI parity — CI merges main into the PR branch):
|
||||
```bash
|
||||
git fetch origin main --quiet
|
||||
```
|
||||
- If the current branch is `main`, skip this step.
|
||||
- If the branch is stacked on another feature branch (not main), skip this step.
|
||||
Detect: `git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null` — if the upstream is NOT `origin/main` (e.g., another feature branch), skip rebase.
|
||||
- Otherwise, rebase:
|
||||
```bash
|
||||
git rebase origin/main
|
||||
```
|
||||
- If the rebase has conflicts, resolve them:
|
||||
1. For each conflicted file, read the file and understand both sides of the conflict
|
||||
2. Resolve by keeping the correct combination of both changes (don't just pick one side)
|
||||
3. `git add <resolved-file>` then `git rebase --continue`
|
||||
4. Repeat for each conflicting commit until the rebase completes
|
||||
5. If a conflict is too ambiguous to resolve confidently, abort (`git rebase --abort`) and ask the user for guidance
|
||||
**Create a task for each step below and mark them as completed as you go.** This pipeline must run in order — formatting before linting prevents formatter-induced lint failures.
|
||||
|
||||
2. **Format** (prevents formatter-induced lint failures):
|
||||
- `make -C apps/backend fmt`
|
||||
- `cd apps && pnpm format`
|
||||
### 1. Rebase on main
|
||||
|
||||
3. **Verify in parallel** where possible:
|
||||
- `make -C apps/backend test lint`
|
||||
- `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web lint`
|
||||
Ensures CI parity — CI merges main into the PR branch.
|
||||
|
||||
4. **Fix issues** — do NOT just report them:
|
||||
- Read each failing file at the reported line number
|
||||
- Fix the root cause (don't suppress warnings or add ignores)
|
||||
- Common fixes:
|
||||
- **Type errors**: fix the type, add a missing import, or correct the function signature
|
||||
- **Lint — function too long**: extract a helper function or sub-component
|
||||
- **Lint — file too long**: split the file into smaller, cohesive files grouped by responsibility (e.g., separate types, helpers, constants, or sub-domains into their own files)
|
||||
- **Lint — cyclomatic/cognitive complexity**: simplify conditionals, extract early returns, break into smaller functions
|
||||
- **Lint — unused imports**: remove them
|
||||
- **Lint — duplicate strings**: extract to a constant
|
||||
- **Test failures**: read the test, understand the assertion, fix the code (not the test) unless the test is outdated
|
||||
- After fixing, re-run only the failed command to confirm the fix
|
||||
```bash
|
||||
git fetch origin main --quiet
|
||||
```
|
||||
|
||||
5. **Repeat** steps 3-4 until all commands pass. If a fix introduces new issues, address those too.
|
||||
- If the current branch is `main`, skip this step.
|
||||
- If the branch is stacked on another feature branch (not main), skip this step.
|
||||
Detect: `git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null` — if the upstream is NOT `origin/main` (e.g., another feature branch), skip rebase.
|
||||
- Otherwise, rebase:
|
||||
```bash
|
||||
git rebase origin/main
|
||||
```
|
||||
- If the rebase has conflicts, resolve them:
|
||||
1. For each conflicted file, read the file and understand both sides of the conflict
|
||||
2. Resolve by keeping the correct combination of both changes (don't just pick one side)
|
||||
3. `git add <resolved-file>` then `git rebase --continue`
|
||||
4. Repeat for each conflicting commit until the rebase completes
|
||||
5. If a conflict is too ambiguous to resolve confidently, abort (`git rebase --abort`) and ask the user for guidance
|
||||
|
||||
6. **Done** when all pass cleanly: rebase, fmt, typecheck, test, lint.
|
||||
### 2. Format
|
||||
|
||||
Run formatters first — they may change line lengths which affects linter results.
|
||||
|
||||
- `make -C apps/backend fmt`
|
||||
- `cd apps && pnpm format`
|
||||
|
||||
### 3. Verify in parallel
|
||||
|
||||
Run these in parallel where possible:
|
||||
|
||||
- `make -C apps/backend test lint`
|
||||
- `cd apps && pnpm --filter @kandev/web typecheck && pnpm --filter @kandev/web lint`
|
||||
|
||||
### 4. Fix issues
|
||||
|
||||
Do NOT just report issues — fix them:
|
||||
|
||||
- Read each failing file at the reported line number
|
||||
- Fix the root cause (don't suppress warnings or add ignores)
|
||||
- Common fixes:
|
||||
- **Type errors**: fix the type, add a missing import, or correct the function signature
|
||||
- **Lint — function too long**: extract a helper function or sub-component
|
||||
- **Lint — file too long**: split the file into smaller, cohesive files grouped by responsibility (e.g., separate types, helpers, constants, or sub-domains into their own files)
|
||||
- **Lint — cyclomatic/cognitive complexity**: simplify conditionals, extract early returns, break into smaller functions
|
||||
- **Lint — unused imports**: remove them
|
||||
- **Lint — duplicate strings**: extract to a constant
|
||||
- **Test failures**: read the test, understand the assertion, fix the code (not the test) unless the test is outdated
|
||||
- After fixing, re-run only the failed command to confirm the fix
|
||||
|
||||
### 5. Repeat
|
||||
|
||||
Repeat steps 3-4 until all commands pass. If a fix introduces new issues, address those too.
|
||||
|
||||
### 6. Done
|
||||
|
||||
All pass cleanly: rebase, fmt, typecheck, test, lint. Mark all tasks as completed.
|
||||
|
||||
Reference in New Issue
Block a user