Debug Specs
Always use the skill
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
When to Use
- The user observes a bug in the running application (visual, behavioral, crash, performance).
- A conformance test or unit test is failing.
- The generated code does something unexpected or incorrect.
- The user points to a specific functional spec that seems wrong.
Guiding Principle
Generated code in
and
is
read-only — it exists solely as evidence for diagnosis. All fixes are applied exclusively to the
spec files. The workflow is: observe → read generated code → trace to spec → fix the spec.
Input
- The module name — identifies the
plain_modules/<module_name>/
- The user's observation — what is wrong? This can be a bug description, a screenshot, a test failure, an error message, or a general "this doesn't work right."
- Optional: a specific functional spec — if the user suspects a particular spec, start there. Otherwise, investigate broadly.
Phase 1 — Understand the Context
- Read the file(s) for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read and chains.
- Read the user's observation carefully. Rephrase it back to confirm understanding. Identify:
- What is the expected behavior?
- What is the actual behavior?
- Is this a visual issue, a logic issue, a crash, or a data issue?
Phase 2 — Investigate the Generated Code
Read files in
plain_modules/<module_name>/
to understand what the renderer produced.
Do not modify any generated files.2a. Narrow the search
If the user pointed to a specific spec or area:
- Identify which generated files implement that spec's behavior.
- Read those files to understand the current implementation.
If the investigation is broad:
- Start from the entry point and follow the execution path related to the observed bug.
- Use the observation to narrow down: UI issue → look at widgets/views, logic issue → look at business logic/providers, data issue → look at models/repositories.
2b. Read the relevant generated code
For each relevant file:
- Read the code and understand what it does.
- Compare the behavior to what the spec says it should do.
- Note any discrepancies — places where the code doesn't match the spec's intent.
2c. Check conformance tests and unit tests (if relevant)
If the bug manifests as a test failure:
- Read the failing test in
conformance_tests/<module_name>/
plain_modules/<module_name>/test/
- Understand what the test expects vs. what the implementation does.
- Determine whether the test expectation is correct (matches the spec) or incorrect (doesn't match the spec).
Phase 3 — Diagnose the Root Cause
Trace the issue from the generated code back to the specs. There are five possible root causes — determine which one applies before making changes:
| Root Cause | Symptom | Fix |
|---|
| Ambiguous spec | The spec is correct in intent, but vague enough that the renderer interpreted it differently than intended. | Add explicit detail to the spec to eliminate the ambiguity. |
| Missing spec | The desired behavior is not covered by any spec. The renderer had no guidance and either did nothing or made an arbitrary choice. | Add a new functional spec using the skill. |
| Conflicting specs | Two specs contradict each other, causing the renderer to produce inconsistent behavior. | Use the skill. |
| Incorrect spec | The spec explicitly describes the wrong behavior. The renderer implemented it faithfully, but the spec itself is wrong. | Rewrite the spec to describe the correct behavior. |
| Missing implementation req | The spec is correct, but the implementation req doesn't provide enough guidance for the renderer to produce the right code (e.g., missing library, missing architectural constraint, missing platform detail). | Add or update the implementation req using the add-implementation-requirement
|
How to diagnose
- Read the spec that governs the buggy behavior. Does it clearly and unambiguously describe the correct behavior?
- If the spec is clear and correct but the code is wrong → ambiguous spec (the renderer misinterpreted it) or missing implementation req.
- If the spec doesn't mention the behavior at all → missing spec.
- If the spec explicitly describes the wrong behavior → incorrect spec.
- Check for conflicts. Could another spec be overriding or contradicting this behavior?
- Read all functional specs that touch the same concepts.
- If two specs are in tension → conflicting specs.
- Check implementation reqs. Is the renderer missing guidance on how to implement correctly?
- Does the implementation req specify the right library, pattern, or constraint?
- If a platform-specific or framework-specific detail is missing → missing implementation req.
Phase 4 — Fix the Specs
Apply the fix based on the diagnosed root cause. Use the appropriate skill:
| Root Cause | Skill to Use |
|---|
| Ambiguous spec | Edit the spec inline — add sub-bullets or reword for clarity |
| Missing spec | |
| Conflicting specs | |
| Incorrect spec | Edit the spec inline — rewrite the incorrect part |
| Missing implementation req | add-implementation-requirement
|
Fix guidelines
- Minimal changes. Only modify what is necessary to fix the observed bug. Avoid rewriting unrelated specs.
- Preserve chronological order. If adding a new spec, place it correctly relative to existing specs.
- Stay language-agnostic. Functional specs describe behavior, not implementation. Platform-specific guidance belongs in implementation reqs.
- Respect the 200 LOC limit. If a fix makes a spec too complex, use to split it.
- Check for new conflicts. After editing, verify the fix doesn't conflict with other specs by running once with the edited spec(s) plus every existing spec that touches the same concepts. The batched analyzer reports all conflicting pairs in a single call; resolve each with .
Phase 5 — Verify and Report
- Re-read the modified file(s) in full to confirm correctness.
- Summarize the findings for the user:
- What was observed (the bug)
- What the generated code was doing (the symptom in code)
- Which spec(s) caused the issue (the root cause)
- What was changed in the specs (the fix)
- What to expect after re-rendering
- If uncertain, present the diagnosis and proposed fix to the user for confirmation before making changes. Some bugs have multiple possible causes — when in doubt, explain the options and let the user decide.
Debugging Strategies
Strategy 1: Observation-Driven (most common)
Start from the user's observation and work backward through the code to the spec.
User sees bug → Read generated code → Find the responsible code path →
Identify which spec governs that code → Diagnose why the spec produced wrong code →
Fix the spec
Strategy 2: Spec-Focused
The user suspects a specific spec. Compare the spec directly against the generated code.
User points to spec → Read the spec → Find the generated code that implements it →
Compare spec intent vs. code behavior → Diagnose the gap → Fix the spec
Strategy 3: Test-Failure-Driven
A test is failing. Use the test as the entry point.
Read failing test → Understand what it expects → Read the implementation →
Determine if the test or the implementation is wrong → Trace back to the spec →
Fix the spec (or test reqs/acceptance tests if the test itself is wrong)
Strategy 4: Differential
The bug appeared after a new spec was added. Compare before and after.
Identify the newly added spec → Read the specs it might conflict with →
Check if the new spec introduced the bug → Use resolve-spec-conflict or
revise the new spec
Common Pitfalls
Fixing the code instead of the spec
Never modify files in
or
. Even if the fix is obvious in the code, the change must be made in the
file so it persists across re-renders.
Treating symptoms instead of root causes
If the user says "the button is in the wrong place," don't just add positioning detail. Investigate why the renderer placed it there — the root cause might be a missing layout spec, an ambiguous screen description, or a conflict with another spec.
Over-specifying the fix
Adding too much implementation detail to a functional spec (e.g., specific pixel values, widget names, CSS properties) makes it brittle. Prefer behavior-level fixes. Use implementation reqs for platform-specific guidance.
Ignoring ripple effects
A spec fix may affect other specs that reference the same concepts. Always check neighboring specs for conflicts after making a change.
Validation Checklist