# Phase 01.6: Fix Agent Overriding Examples in Scaffolded File - Research

**Researched:** 2026-01-26
**Domain:** Prompt Engineering / Agent Protocol Design
**Confidence:** HIGH

## Summary

The research focused on preventing GSD-Lite agents from destructively overwriting existing scaffolded artifacts (`STATE.md`, `WORK.md`, etc.) during initialization or session start. The core issue is that agents, when encountering a "new phase" or "setup" instruction, may mistakenly interpret this as a directive to reset state files to their template defaults, erasing user progress and data.

The solution involves reinforcing the "Read-First, Write-Second" protocol at the two primary entry points: `PROTOCOL.md` (the router) and `moodboard.md` (the planning entry point). By explicitly forbidding file overwrites and mandating that agents adopt existing file content as the "source of truth," we can ensure state persistence.

**Primary recommendation:** Add explicit "Safety Rules" to `PROTOCOL.md` and "Entry Condition Checks" to `moodboard.md` that mandate reading existing artifacts before any write operation.

## Standard Stack

This phase involves modifying Markdown-based agent instructions. No new libraries or tools are required.

### Artifacts to Modify
| File | Role | Modification |
|------|------|--------------|
| `src/gsd_lite/template/PROTOCOL.md` | Router & Global Rules | Add "Safety Protocol" section forbidding overwrites. |
| `src/gsd_lite/template/workflows/moodboard.md` | Planning Entry Point | Add "Initialization Check" to verify existing state before assuming a fresh start. |

## Architecture Patterns

### The "Adoption" Pattern
Instead of "Initialization" (which implies creating from scratch), the agent should follow an "Adoption" pattern:
1.  **Check:** Does `STATE.md` exist?
2.  **If No:** Create from template (Scaffold).
3.  **If Yes:** Read content, parse current state, and **resume** or **append**.
4.  **Never:** Overwrite an existing file with a template.

### Code Examples (Prompt Engineering)

#### 1. Protocol Safety Rule (for `PROTOCOL.md`)
```markdown
## 🛡️ Safety Protocol (CRITICAL)

**NEVER overwrite existing artifacts with templates.**

Before writing to `STATE.md`, `WORK.md`, or `INBOX.md`:
1. **Check existence:** run `ls gsd-lite/`
2. **Read first:** If file exists, `read` it to understand current state.
3. **Append/Update:** Only add new information or update specific fields.
4. **Preserve:** Keep all existing history, loops, and decisions.

*Violation of this rule causes data loss and is a critical failure.*
```

#### 2. Entry Condition Check (for `moodboard.md`)
```markdown
## Initialization Check

**BEFORE starting a new phase:**
1. Check if `gsd-lite/STATE.md` exists.
2. If it exists, READ IT.
   - If `Current Mode` is `none` or `planning`, RESUME that session.
   - Do NOT reset the file to blank template.
3. If it does NOT exist, only then can you initialize with the template.
```

## Common Pitfalls

### Pitfall 1: "Fresh Start" Bias
**What goes wrong:** Agents often interpret "Start a new phase" as "Delete everything and start fresh."
**Why it happens:** LLMs associate "initialization" with "clean slate."
**How to avoid:** Use language like "Resume," "Adopt," or "Continue" instead of "Initialize" when files might exist. explicitly forbid "Reset" or "Overwrite."

### Pitfall 2: Template Blindness
**What goes wrong:** Agent reads the *template* file during its own setup (e.g., via RAG or context) and assumes that *is* the current state, then writes it out.
**How to avoid:** Ensure the agent distinguishes between "Reference Template" (instructions) and "Live Artifact" (user data). The instructions must say "Use the FORMAT from the template, but preserve the DATA from the live file."

## Open Questions

1.  **Question:** Should we add a `VERSION` check?
    - **Context:** If the template version (`VERSION` file) is newer than the project, should the agent attempt to migrate?
    - **Recommendation:** Out of scope for this "fix" phase. For now, strict preservation is safer than complex auto-migration.

## Sources

### Primary (HIGH confidence)
- **Codebase Analysis:** Reviewed `src/gsd_lite/template/PROTOCOL.md` and `src/gsd_lite/template/workflows/moodboard.md` to identify the current instruction gaps.
- **Phase Context:** Analyzed the "Phase 1.6" description and "Implementation Decisions" provided in the prompt.

### Secondary (MEDIUM confidence)
- **Self-Correction:** Verified that `__main__.py` already handles safe scaffolding (no overwrite), confirming the issue lies purely in Agent behavior/instructions.

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH - Pure markdown edits.
- Architecture: HIGH - "Read-First" is a standard safety pattern.
- Pitfalls: HIGH - Common LLM behavior patterns observed in GSD context.

**Research date:** 2026-01-26
