plain-forge 1.0.1

package/forge/skills/consolidate-concepts/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: consolidate-concepts
+description: >-
+  Gather concept definitions scattered across multiple modules into a single
+  shared import module in template/. Removes the moved definitions from the
+  original modules and adds the new import to their frontmatter. Use when
+  concepts are duplicated or spread across modules and should be centralized.
+---
+
+# Consolidate Concepts
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## When to Use
+
+- Multiple modules define the same or closely related concepts independently.
+- A `requires` chain uses long `exported_concepts` lists to share definitions that would be simpler as an import.
+- After a `refactor-module` split, shared concepts ended up duplicated or awkwardly exported.
+- The user wants a single source of truth for domain concepts used across modules.
+
+## Guiding Principle
+
+This is a structural refactoring. The **behavior** of every affected module must remain **identical**. No functional spec, implementation req, or test req is changed. Only concept definitions move — from scattered locations into one shared import module — and the modules' `import` lists are updated to reference it.
+
+## Input
+
+The set of modules to consolidate from, plus optionally the name for the new (or existing) import module. If not specified, ask the user.
+
+## Phase 1 — Analyze Concepts Across Modules
+
+1. **Read all source modules.** For each `.plain` file involved, read the full file including frontmatter, definitions, implementation reqs, test reqs, and functional specs. Also read their `import` and `requires` chains.
+2. **Build a concept inventory.** For each concept defined across all source modules, record:
+   - Where it is defined (which file, which line)
+   - Which modules reference it (in definitions, functional specs, implementation reqs, or test reqs)
+   - Whether it is currently in an `exported_concepts` list
+   - Which other concepts it references in its definition (dependency graph)
+3. **Identify consolidation candidates.** A concept should be consolidated if:
+   - It is defined in one module but referenced by specs in another module (currently shared via `exported_concepts`)
+   - It is duplicated across multiple modules
+   - It is a foundational domain concept that logically belongs in a shared vocabulary
+4. **Identify concepts that should stay local.** A concept should remain in its module if:
+   - It is only used within that single module's specs and definitions
+   - It is an internal implementation detail not meaningful outside that module
+
+## Phase 2 — Plan the Consolidation
+
+Present the plan to the user and get explicit confirmation before making changes.
+
+### 2a. Choose the target import module
+
+- **New import module** — create a new `.plain` file in `template/`. Choose a name that reflects the shared domain (e.g., `template/myapp-concepts.plain`).
+- **Existing import module** — add the concepts to an import module that is already used by the affected modules. This avoids adding another import reference.
+
+If the target is an existing import module, read it fully to understand what it already contains.
+
+### 2b. Determine which concepts move
+
+For each consolidation candidate, confirm:
+- The concept will be removed from its current module's `***definitions***` section.
+- The concept will be added to the target import module's `***definitions***` section.
+- The concept's full definition text (including all sub-bullets for attributes and constraints) is moved verbatim.
+
+### 2c. Determine concept ordering in the target
+
+Concepts in the import module must be ordered so that every concept is defined **after** any concepts it references. Use the dependency graph from Phase 1 to establish a valid topological order.
+
+### 2d. Determine import and export changes
+
+For each affected module, determine the frontmatter changes:
+
+| Change | When |
+|--------|------|
+| Add the new import to `import` list | Module does not already import the target |
+| Remove concepts from `exported_concepts` | Concepts that were exported only to share definitions — now handled by the import |
+| Keep concepts in `exported_concepts` | Concepts that downstream `requires` modules still need via export (because those downstream modules do not import the new template) |
+
+**Important:** `import` provides definitions to the importing module. `exported_concepts` on a `requires` module provides concepts to downstream modules in the build chain. If a downstream module will now `import` the shared template directly, the concept can be removed from `exported_concepts`. If a downstream module does **not** import the template, the concept must remain exported.
+
+### 2e. Present the plan
+
+Summarize for the user:
+- Target import module (new or existing) and its path
+- List of concepts being moved, with source module for each
+- List of concepts staying local (and why)
+- Frontmatter changes per module (`import` additions, `exported_concepts` removals)
+- Confirmation that no functional specs, implementation reqs, or test reqs are changing
+
+Get explicit user confirmation before proceeding.
+
+## Phase 3 — Execute
+
+### 3a. Create or update the import module
+
+If creating a new import module:
+1. Create `template/<name>.plain` with YAML frontmatter. If it needs concepts from another import, add that to its own `import` list.
+2. Add a `***definitions***` section with all consolidated concepts in dependency order.
+3. Do **not** add `***functional specs***` — import modules must not contain them.
+
+If updating an existing import module:
+1. Read the current file.
+2. Insert the new concepts into the `***definitions***` section, respecting dependency order relative to existing concepts.
+3. Verify no concept name collisions with concepts already in the file or its own imports.
+
+### 3b. Update each source module
+
+For each module that had concepts moved out:
+
+1. **Remove the concept definitions** from the module's `***definitions***` section. Remove the full definition including all sub-bullets.
+2. **Add the import** to the module's YAML frontmatter `import` list (if not already present).
+3. **Update `exported_concepts`** — remove concepts that no longer need to be exported (see 2d).
+4. **Do not touch** `***functional specs***`, `***implementation reqs***`, or `***test reqs***` — concept references (`:ConceptName:`) in these sections remain unchanged since the concept is now provided by the import.
+
+### 3c. Update downstream modules (if applicable)
+
+If concepts were removed from a module's `exported_concepts` and downstream `requires` modules relied on them:
+1. Add the new import to the downstream module's `import` list so it gets the concepts directly.
+2. Verify the downstream module's specs can still resolve all concept references.
+
+## Phase 4 — Verify
+
+### 4a. Concept availability check
+
+For every affected module (source modules, downstream modules, and the import module itself):
+- [ ] Every `:Concept:` referenced in functional specs is resolvable (defined locally, via import, or via exported concepts from requires)
+- [ ] Every `:Concept:` referenced in definitions is defined before the concept that references it
+- [ ] Every `:Concept:` referenced in implementation reqs and test reqs is resolvable
+
+### 4b. No duplicates check
+
+- [ ] No concept is defined in both the import module and a source module
+- [ ] No concept is defined in both the import module and another import that a source module uses
+- [ ] Concept names are globally unique across each module's full resolution scope (local + imports + requires exports)
+
+### 4c. Definition integrity check
+
+- [ ] Each moved concept's definition text is identical to the original — no rewording, no lost sub-bullets
+- [ ] Concept ordering in the import module respects the dependency graph (no forward references)
+
+### 4d. No behavioral change check
+
+- [ ] No `***functional specs***` were modified in any module
+- [ ] No `***implementation reqs***` were modified in any module
+- [ ] No `***test reqs***` were modified in any module
+- [ ] No `***acceptance tests***` were modified in any module
+
+### 4e. Structural validation
+
+For the import module:
+- [ ] File is in the `template/` directory
+- [ ] Does not contain `***functional specs***`
+- [ ] Does not use `requires`
+- [ ] YAML frontmatter is correctly formatted
+
+For each source module:
+- [ ] YAML frontmatter `import` list includes the target import module
+- [ ] `exported_concepts` is correct (no over-export, no missing exports)
+- [ ] Module still has at least one functional spec and one implementation req
+
+### 4f. Read all modified files
+
+Read each modified `.plain` file in full and present the changes to the user for approval. If the user requests changes, apply them and re-verify.
+
+## Common Pitfalls
+
+### Moving a concept that is only used locally
+If a concept is only referenced within a single module, consolidating it into a shared import adds unnecessary coupling. Keep it local.
+
+### Forgetting to update downstream requires modules
+When a concept is removed from `exported_concepts`, any module that `requires` the source module and references that concept will break — unless it now imports the shared template. Always trace the full dependency chain.
+
+### Breaking concept ordering
+Concepts in the import module must be topologically ordered. If `:Meal:` references `:MealType:` in its definition, then `:MealType:` must appear first. The source modules may have had them in the right order locally, but merging concepts from different modules requires re-establishing a valid order.
+
+### Creating circular imports
+An import module cannot `import` a module that directly or indirectly imports it back. If the shared concepts reference concepts from an existing template, the new import module should itself import that template — not the other way around.
+
+### Removing concepts from exported_concepts prematurely
+Only remove a concept from `exported_concepts` if **every** downstream `requires` module that needs it will now get it via `import`. If even one downstream module does not import the shared template, the export must stay.
+
+## Validation Checklist
+
+- [ ] User confirmed the consolidation plan before execution
+- [ ] All moved concepts are defined in the import module with identical text
+- [ ] Concepts are in valid dependency order in the import module
+- [ ] No concept is defined in both the import module and a source module
+- [ ] Every affected module's `import` list includes the target import module
+- [ ] `exported_concepts` updated correctly — no missing exports, no unnecessary exports
+- [ ] All concept references in all affected modules resolve correctly
+- [ ] No functional specs, implementation reqs, test reqs, or acceptance tests were modified
+- [ ] Import module is in `template/` and has no functional specs or requires
+- [ ] No circular imports introduced
+- [ ] Downstream requires modules updated if needed
+- [ ] User approved the final result

package/forge/skills/create-import-module/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: create-import-module
+description: >-
+  Create a ***plain import module that provides shared definitions,
+  implementation reqs, and test reqs for other modules to import. Use when
+  the user wants to create a new .plain file that contains only definitions,
+  implementation reqs, and/or test reqs — no functional specs.
+---
+
+# Create Import Module
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## What an Import Module Is
+
+An import module is a `.plain` file that lives in the **`template/`** directory and contains **only** `***definitions***`, `***implementation reqs***`, and/or `***test reqs***`. It must **not** contain `***functional specs***` and must **not** use `requires` in its frontmatter. Other modules pull in its content via the `import` field in their YAML frontmatter, gaining access to its definitions and reqs.
+
+Use import modules for:
+- Sharing concept definitions across multiple modules
+- Providing common implementation requirements (e.g., technology stack, coding standards)
+- Providing common test requirements
+- Creating reusable foundational structure (templates)
+
+If the module needs functional specs (i.e., it describes what software should do), it is not an import module — see the `create-requires-module` skill.
+
+## Workflow
+
+1. **Determine what shared content this module should provide** — which definitions, implementation reqs, or test reqs will other modules need?
+2. **Create the `.plain` file in the `template/` directory** with YAML frontmatter. Use `required_concepts` to declare concepts that importing modules must define. It may optionally `import` other templates for layered reuse, but must **not** use `requires`.
+3. **Add the shared content** — definitions, implementation reqs, and/or test reqs.
+4. **Do not add `***functional specs***`** — import modules must not contain functional specs.
+5. **Verify concept availability** — ensure all `:Concepts:` referenced are either defined in this module, provided by its own imports, declared as `required_concepts`, or are predefined concepts.
+
+## Format
+
+The `import` field is a list of module paths in the YAML frontmatter:
+
+```plain
+---
+import:
+  - base_template
+required_concepts: [":AppName:"]
+description: Shared API definitions and reqs
+---
+
+***definitions***
+- :ApiClient: is the HTTP client used to communicate with external services.
+- :ApiResponse: is the response returned by :ApiClient:.
+
+***implementation reqs***
+- :Implementation: should handle HTTP errors by raising appropriate exceptions.
+- :ApiClient: should support configurable timeouts.
+
+***test reqs***
+- :ConformanceTests: should mock all external HTTP calls made by :ApiClient:.
+```
+
+The default import directory is `template/` — the `template/` prefix is not needed in import paths. The `.plain` extension is omitted. Note the absence of `***functional specs***` — import modules must not have them.
+
+## Satisfying Required Concepts
+
+If an imported template declares `required_concepts`, the importing module **must** define those concepts in its own `***definitions***` section:
+
+```plain
+---
+import:
+  - auth_template
+---
+
+> auth_template declares required_concepts: [":AuthSchema:", ":AuthApiSpec:"]
+> So this module must define them:
+
+***definitions***
+- :AuthSchema: is the JSON schema describing the authentication data structure.
+- :AuthApiSpec: is the OpenAPI specification for the external service's auth endpoint.
+```
+
+## Import vs Requires
+
+| Aspect | `import` | `requires` |
+|--------|----------|------------|
+| Pulls in definitions | Yes | No (only `exported_concepts`) |
+| Pulls in implementation reqs | Yes | No |
+| Pulls in test reqs | Yes | No |
+| Pulls in functional specs | No | Yes (as previous requirements) |
+| Copies generated code | No | Yes |
+| Typical use | Templates, shared definitions | Build dependency chain |
+
+## Validation Checklist
+
+- [ ] Module file is in the `template/` directory
+- [ ] Module does **not** contain `***functional specs***`
+- [ ] Module does **not** use `requires` in its frontmatter
+- [ ] Contains at least one of: definitions, implementation reqs, or test reqs
+- [ ] All `required_concepts` from any imports this module itself uses are satisfied
+- [ ] `required_concepts` declared for any concepts referenced but not defined here
+- [ ] No concept name collisions between this module's imports and local definitions
+- [ ] YAML frontmatter is correctly formatted between `---` markers

package/forge/skills/create-requires-module/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: create-requires-module
+description: >-
+  Create a ***plain module that uses requires to depend on another module in
+  the build chain. Use when the user wants to create a new .plain file that
+  builds on top of a previously built module, inheriting its functional specs
+  and generated code as a starting point.
+---
+
+# Create Requires Module
+
+Always use the skill `load-plain-reference` to retrieve the ***plain syntax rules — but only if you haven't done so yet.
+
+## What Requires Does
+
+`requires` establishes a build ordering between modules. The required module is built **before** the current one. This does not necessarily mean the current module extends or depends on the required module's code — it may be completely independent. The `requires` relationship simply ensures the build order is correct.
+
+When this module is rendered:
+- The required module's generated code (`plain_modules/<required_module>`) is copied as the starting point.
+- The required module's `***functional specs***` become visible as **previous functional specs**.
+- Only `exported_concepts` from the required module are available (not its full definitions).
+
+Use `requires` for:
+- Ensuring a module is built after another in the build chain
+- Building on top of an existing module's functionality
+- Extending a base module with additional features
+
+If you only need shared definitions and reqs (no functional specs, no generated code), use `import` instead — see the `create-import-module` skill.
+
+## Workflow
+
+1. **Identify the dependency.** Determine which module this new module builds on. That module must already exist and be renderable.
+2. **Create the `.plain` file at the repository root** with YAML frontmatter containing the `requires` field. Modules with functional specs live at the root, not in `template/`.
+3. **Review the required module's functional specs** — they will be treated as previous requirements. Your new functional specs must not conflict with them.
+4. **Review the required module's `exported_concepts`** — only those concepts are available to reference from the required module.
+5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module.
+6. **Check for conflicts** between your new functional specs and the required module's specs.
+
+## Format
+
+The `requires` field is a list of module paths in the YAML frontmatter:
+
+```plain
+---
+requires:
+  - base_module
+import:
+  - shared_template
+description: Extended module that builds on base_module
+---
+
+***definitions***
+- :NewFeature: is a feature added by this module.
+
+***functional specs***
+
+- The system should support :NewFeature:.
+```
+
+A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).
+
+## Exported Concepts
+
+The required module controls what concepts are visible via `exported_concepts`:
+
+```plain
+> In the required module's frontmatter:
+---
+exported_concepts: [":StorageClient:", ":BackupResult:"]
+---
+```
+
+Only `:StorageClient:` and `:BackupResult:` would be available to modules that `require` this one. All other concepts from the required module are internal.
+
+## Chronological Ordering with Requires
+
+Functional specs from `requires` modules are considered **previous functional specs**. This means:
+- They are already rendered and their code exists.
+- Your new specs are rendered after them, with full awareness of what they defined.
+- Your new specs must not conflict with the required module's specs.
+- The renderer sees the required module's functional specs as context when rendering yours.
+
+The current module may or may not be functionally related to the required module. In some cases `requires` simply enforces build order — the two modules may be independent pieces of the same project that need to be built in sequence.
+
+## Import vs Requires
+
+| Aspect | `import` | `requires` |
+|--------|----------|------------|
+| Pulls in definitions | Yes | No (only `exported_concepts`) |
+| Pulls in implementation reqs | Yes | No |
+| Pulls in test reqs | Yes | No |
+| Pulls in functional specs | No | Yes (as previous requirements) |
+| Copies generated code | No | Yes |
+| Typical use | Templates, shared definitions | Build dependency chain |
+
+## Validation Checklist
+
+- [ ] Module file is at the repository root (not in `template/`)
+- [ ] Required module exists and is renderable
+- [ ] Required module's `exported_concepts` provide the concepts you need
+- [ ] New functional specs do not conflict with the required module's specs
+- [ ] Module has at least one functional spec and one implementation req
+- [ ] Both `requires` and `import` are used correctly (not mixed up)
+- [ ] YAML frontmatter is correctly formatted between `---` markers

package/forge/skills/debug-specs/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: debug-specs
+description: >-
+  Investigate a bug observed in the running application by reading the generated
+  code in plain_modules/, tracing the issue back to the specs, and fixing only
+  the .plain files. Generated code is never modified. Use when the user reports
+  unexpected behavior, visual glitches, crashes, or incorrect logic in the app.
+---
+
+# Debug Specs
+
+Always use the skill `load-plain-reference` 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 `plain_modules/` and `conformance_tests/` is **read-only** — it exists solely as evidence for diagnosis. All fixes are applied exclusively to the `.plain` spec files. The workflow is: observe → read generated code → trace to spec → fix the spec.
+
+## Input
+
+1. **The module name** — identifies the `plain_modules/<module_name>/` directory and the corresponding `.plain` file(s).
+2. **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."
+3. **Optional: a specific functional spec** — if the user suspects a particular spec, start there. Otherwise, investigate broadly.
+
+## Phase 1 — Understand the Context
+
+1. **Read the `.plain` file(s)** for the module — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read `import` and `requires` chains.
+2. **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:
+1. Read the code and understand what it does.
+2. Compare the behavior to what the spec says it should do.
+3. 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:
+1. Read the failing test in `conformance_tests/<module_name>/` or `plain_modules/<module_name>/test/`.
+2. Understand what the test expects vs. what the implementation does.
+3. 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 `add-functional-spec` skill. |
+| **Conflicting specs** | Two specs contradict each other, causing the renderer to produce inconsistent behavior. | Use the `resolve-spec-conflict` 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` skill. |
+
+### How to diagnose
+
+1. **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**.
+2. **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**.
+3. **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 | `add-functional-spec` |
+| Conflicting specs | `resolve-spec-conflict` |
+| 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 `break-down-func-spec` to split it.
+- **Check for new conflicts.** After editing, verify the fix doesn't conflict with other specs by running `analyze-func-specs` 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 `resolve-spec-conflict`.
+
+## Phase 5 — Verify and Report
+
+1. **Re-read the modified `.plain` file(s)** in full to confirm correctness.
+2. **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
+3. **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 `plain_modules/` or `conformance_tests/`. Even if the fix is obvious in the code, the change must be made in the `.plain` 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
+
+- [ ] User's observation is clearly understood (expected vs. actual behavior)
+- [ ] Generated code has been read to understand the current implementation
+- [ ] Root cause is diagnosed (ambiguous / missing / conflicting / incorrect / missing impl req)
+- [ ] Fix is applied in the `.plain` file(s) only — no generated code modified
+- [ ] Fix is minimal and targeted to the observed bug
+- [ ] Fix does not introduce new conflicts with existing specs
+- [ ] Modified specs respect the 200 LOC limit
+- [ ] Modified specs remain language-agnostic
+- [ ] Chronological ordering is preserved
+- [ ] Summary of findings and fix presented to the user