# Section 4: Prompt Updates (Efficiency Rules + QA Checklist)

## Overview

This section adds two new sections to the MCP prompt file at `src/godotiq/prompts/godot_development_prompt_v2.md`:

1. **Efficiency Rules** -- five rules that prevent the agent from overthinking and making redundant tool calls. Inserted after the "Token Efficiency (CRITICAL)" section and before "Mandatory Workflows".
2. **MANDATORY: Final QA** -- a six-step QA checklist the agent must follow before declaring any task done. Inserted after the "Creation Workflow -- `build_scene`" subsection (Phase 6 and Key Principles) and before "Token Efficiency (CRITICAL)".

These are pure markdown changes. No Python or GDScript code is involved.

## Dependencies

- **No hard dependencies on other sections.** This section can be implemented in parallel with all others.
- Section 1 (editor state) introduces `_editor_state` in every bridge response. The Efficiency Rules reference `_editor_state`, but the prompt text works regardless of whether Section 1 is deployed yet.

## Files to Modify

- `src/godotiq/prompts/godot_development_prompt_v2.md` -- add two new markdown sections

## Tests (Write First)

Create `tests/test_prompts/test_prompt_content.py` and `tests/test_prompts/__init__.py`.

```python
# File: tests/test_prompts/test_prompt_content.py

from pathlib import Path
import pytest

PROMPT_PATH = Path(__file__).resolve().parents[2] / "src" / "godotiq" / "prompts" / "godot_development_prompt_v2.md"


@pytest.fixture
def prompt_text():
    """Load the prompt file as a string."""
    return PROMPT_PATH.read_text(encoding="utf-8")


class TestQAChecklist:
    """Verify QA checklist section exists with required content."""

    def test_prompt_is_loadable(self, prompt_text):
        assert len(prompt_text) > 0

    def test_qa_section_exists(self, prompt_text):
        assert "MANDATORY: Final QA" in prompt_text

    def test_qa_contains_spatial_audit(self, prompt_text):
        assert "spatial_audit" in prompt_text

    def test_qa_contains_cannot_see_constraint(self, prompt_text):
        assert "CANNOT see" in prompt_text or "NEVER say" in prompt_text

    def test_qa_after_creation_workflow(self, prompt_text):
        assert prompt_text.index("MANDATORY: Final QA") > prompt_text.index("Creation Workflow")

    def test_qa_before_token_efficiency(self, prompt_text):
        assert prompt_text.index("MANDATORY: Final QA") < prompt_text.index("Token Efficiency")


class TestEfficiencyRules:
    """Verify efficiency rules section exists with required content."""

    def test_efficiency_section_exists(self, prompt_text):
        assert "Efficiency Rules" in prompt_text

    def test_contains_dont_overthink(self, prompt_text):
        assert "overthink" in prompt_text.lower()

    def test_contains_batch_operations(self, prompt_text):
        assert "Batch operations" in prompt_text

    def test_contains_editor_state_reference(self, prompt_text):
        assert "_editor_state" in prompt_text

    def test_contains_dont_repeat(self, prompt_text):
        assert "repeat tool calls" in prompt_text.lower()

    def test_efficiency_before_mandatory_workflows(self, prompt_text):
        assert prompt_text.index("Efficiency Rules") < prompt_text.index("Mandatory Workflows")
```

## Implementation Details

### File: `src/godotiq/prompts/godot_development_prompt_v2.md`

Two insertions are needed. The current file structure (section headers in order) is approximately:

```
## CRITICAL: How to Build 3D Scenes
  ### Creation Workflow -- build_scene
    #### Phase 1-6 and Key Principles
---
## Token Efficiency (CRITICAL)
---
## Mandatory Workflows
---
## Tool Reference
---
## Spatial Validation
## Node Paths
## GDScript Conventions
## Error Recovery
```

### Insertion 1: "MANDATORY: Final QA" Section

Insert **after** the "Creation Workflow" subsection's "Key Principles" content and **before** the `---` separator and "Token Efficiency (CRITICAL)" section.

Content:

```markdown

### MANDATORY: Final QA (before declaring "done")

Before telling the user the task is complete, you MUST run ALL 6 checks:

1. **Spatial coherence** — `godotiq_spatial_audit(detail="brief")`. Must have 0 critical issues and 0 warnings. If any exist, fix them before proceeding.

2. **Grid/path connectivity** — If you used `build_scene` with grid mode and overrides, check the `warnings` field in the response. If there are connectivity warnings (isolated tiles, gaps in path), fix them with `node_ops` before continuing.

3. **Code quality** — For every `.gd` file you created or modified, call `godotiq_validate(target="res://path/to/file.gd", detail="brief")`. Fix all issues before proceeding.

4. **Signal wiring** — `godotiq_signal_map(detail="brief", find="orphans")`. Must have 0 orphan signals. If any exist, connect or remove them.

5. **Gameplay test** — Run a full play-test sequence:
   ```
   godotiq_run(action="play")
   godotiq_state_inspect(queries=[...])   # verify key game state values
   godotiq_input(actions=[...])           # simulate player actions
   godotiq_state_inspect(queries=[...])   # verify state changed correctly
   godotiq_run(action="stop")
   ```

6. **Report to user** — State what was built, summarize QA results, and EXPLICITLY ask the user to visually verify in the Godot editor. You CANNOT see the game. You MUST ask the user to look.

**NEVER say "I can see the terrain" or "the game looks great" or any variation.** You are an AI with NO visual perception of the Godot editor or game window. You have tool data only. Always phrase it as: "I've completed the build and all QA checks pass. Please open the scene in the editor and verify that [specific things] look correct."
```

### Insertion 2: "Efficiency Rules" Section

Insert **after** the "Token Efficiency (CRITICAL)" section's `---` separator and **before** "Mandatory Workflows".

Content:

```markdown

## Efficiency Rules

1. **Don't overthink -- act.** If you know what tool to call, call it immediately. Don't deliberate for 3 paragraphs about whether to call it. If the call fails, you'll see the error in the response and can adjust. Action is faster than speculation.

2. **Batch operations.** Use `build_scene` for multiple nodes instead of individual `node_ops` calls. Use `script_ops` patch mode for targeted changes instead of rewriting entire files. One tool call that does 20 things beats 20 tool calls that each do 1 thing.

3. **Don't repeat tool calls.** If you already called `project_summary` or `asset_registry` this session, don't call them again -- the project structure hasn't changed. Keep results from previous calls in your conversation context and refer back to them.

4. **Check `_editor_state`.** Every bridge tool response includes an `_editor_state` dict with `open_scene`, `game_running`, and `recent_errors`. Read it after every tool call. If `recent_errors` is not empty, address the errors before continuing. If `open_scene` is wrong or empty, fix it before doing more scene work. This saves you from calling `editor_context` separately.

5. **One script, one validate.** After writing or modifying each `.gd` file, immediately call `godotiq_validate` on it. Don't write 5 scripts and then validate them all at the end -- errors compound and become harder to debug when you can't tell which script introduced the problem.

---
```

### Final File Structure

```
## CRITICAL: How to Build 3D Scenes
  ### Creation Workflow -- build_scene
    #### Phase 1-6 and Key Principles
  ### MANDATORY: Final QA (before declaring "done")     <-- NEW
---
## Token Efficiency (CRITICAL)
---
## Efficiency Rules                                      <-- NEW
---
## Mandatory Workflows
...
## Error Recovery
```

### Key Constraints

- QA checklist is exactly 6 steps, all must be present
- "NEVER say I can see" constraint must be explicit and emphatic
- Efficiency Rules reference `_editor_state` by name (aligns with Section 1)
- Total addition is ~60-80 lines of markdown
- Use `###` (h3) for QA checklist (subsection of "CRITICAL: How to Build 3D Scenes")
- Use `##` (h2) for Efficiency Rules (top-level section)
- Do not modify any existing content
