Prompt file imported from jesscss/jess (
.cursor/commands/start-debugging.md). Copyright stays with the author.
Start Debugging
You are starting a focused debugging session. Follow these steps. The area (extend, mixins, parser, core, jess, etc.) comes from the user or from the current-focus block in docs/state/PROJECT_STATE.md. This workflow is generic so it works for any bug, not just extend.
1. Load state (do not skip)
- Read
docs/state/PROJECT_STATE.md(build shape, verification commands, and current debugging focus if one is active). - If the state file or the user mentions a relevant active plan file, read that too so you know baseline and order of attack.
- For extend, prefer the canonical pointers:
.cursor/rules/subtrees/core__extend.mdcdocs/architecture/core/EXTEND-SEMANTICS.md
2. Run the right baseline
Use section 3 in PROJECT_STATE and the current area to choose what to run. Examples:
| Area | Typical baseline (from PROJECT_STATE §3) |
|---|---|
| extend | cd packages/core && pnpm test -- --run src/ast/__tests__/extend src/ast/extend/__tests__ |
| core | From packages/core: pnpm test -- --run (or the path the user/plan specifies) |
| jess | After building core if needed: pnpm --filter @jesscss/core build then pnpm run test:less:test-data (or a single fixture – see packages/jess/test/less/README.md) |
If the user specified an area (e.g. "extend", "parser"), use that. Otherwise use the current-focus "Area" field or ask. Run the baseline and report: passed, failed, and names of any failing tests.
3. Focus on one case (if user specified)
If the user asked to focus on a specific test or fixture:
- Add
it.only()ordescribe.only()in the relevant test file for that case only. - Re-run the baseline.
- Proceed with the systematic debugging methodology: observe → hypothesize → trace → one small change → run test → update state. Use
syncLog()only; neverconsole.logorJSON.stringifyon nodes.
4. Build dependency first (when crossing packages)
If the area involves packages that depend on another (e.g. jess tests that use core), build the dependency first so tests see updated code. See PROJECT_STATE §1–2. Example: after changing core, run pnpm --filter @jesscss/core build before jess tests.
5. Before ending session
Update docs/state/PROJECT_STATE.md (and the area’s active plan file, if any) with: what you tried, result, next step. Remove any .only before committing.
If the user provided context after the command (e.g. "focus on nested & extend all"), use that to choose the focus in step 3.
