# Phase 1.6: Fix Agent Overriding Examples in Scaffolded File - Context

**Gathered:** 2026-01-26
**Status:** Ready for planning

<domain>
## Phase Boundary

Fix the issue where GSD-lite agents blindly overwrite existing scaffolded artifacts (STATE.md, WORK.md, etc.) during initialization. These files contain critical examples/instructions for the agent. The fix must ensure agents read and respect existing files instead of resetting them.

</domain>

<decisions>
## Implementation Decisions

### Initialization Logic
- **Mandatory Check:** Agent must verify file existence (via `ls` or `read`) before writing any artifact.
- **Read-First:** If files exist, the agent MUST read them to understand the current state and examples.
- **No Overwrite:** Agent is forbidden from overwriting existing files with blank templates.
- **Adoption:** Agent uses the content found in existing files as the starting state (appending new session data while preserving examples).

### Conflict Resolution
- **Action:** If files exist, treat them as the "Live" state.
- **Examples:** Keep examples in the file (do not delete/replace). Append real session data below or alongside them.
- **User Intent:** Assume existing files are intentional (scaffolded) and must be preserved.

### Enforcement Location
- **Workflow Level:** Update `moodboard.md` (the entry point) to explicitly instruct the agent to check for existing `STATE.md` before "initializing".
- **Protocol Level:** Update `PROTOCOL.md` to include a global safety rule: "Never overwrite existing GSD artifacts; read and update them."

### Claude's Discretion
- Exact phrasing of the safety instructions.
- How to format the "Appended" data to distinguish it from "Examples" (if needed).

</decisions>

<specifics>
## Specific Ideas

- "The scaffolded files contain examples how it should follow... it came to naught if it just dumbly override them."
- The agent should see the existing `STATE.md` as "Oh, here is the format and the current state," rather than "I need to make a STATE.md."
- "Least friction" approach: Agent naturally resumes/adopts if files are present.

</specifics>

<deferred>
## Deferred Ideas

- Force Init flag (e.g. `/gsd-init --force`) — Manual deletion is sufficient for now.

</deferred>

---

*Phase: 01.6-fix-agent-overriding-examples-in-scaffolded-file*
*Context gathered: 2026-01-26*
