---
name: "update_story.description should create the ## Description section if it doesn't exist (instead of erroring)"
---

# Story 516: update_story.description should create the ## Description section if it doesn't exist (instead of erroring)

## User Story

**Note:** content stuffed into user_story per bug 509 workaround.

---

## Context

The MCP `update_story` tool's `description` parameter "replaces the `## Description` section content". If the section doesn't exist in the story file, the call **errors out** with `Section '## Description' not found in story file.`

This becomes a real problem when:

1. A story was created via `create_story` (which is buggy per 509 and writes a stub template with no `## Description` section)
2. The user later wants to add a description via `update_story`
3. The update fails with the cryptic "section not found" error

We hit this exact scenario today: after bug 509 dropped the descriptions of 6 stories (500, 504, 505, 506, 507, 508), I tried to recover them by calling `update_story` with `description=...` — and the call errored out because the stub template the buggy `create_story` had written had no `## Description` section. We had to fall back to stuffing everything into the `user_story` field.

## Real user story

As a user calling `update_story.description` on any story (regardless of how it was originally created), I want the call to either replace the existing `## Description` section OR create one if it doesn't exist, so I never have to think about the template structure.

## Implementation note

The simplest fix is in the `update_story_in_file` (or equivalent) function: when looking for the `## Description` section, if not found, **insert it** at a sensible location — probably between `## User Story` and `## Acceptance Criteria` — and then write the description content there.

Related: this story partially covers the workaround for bug 509 (create_story drops description). If 509 is fixed first, the templates would always have a `## Description` section and this wouldn't matter. But this fix is still valuable for older stories created before 509 lands, AND for stories created via legacy paths that don't use the canonical template.

## Observed 2026-04-09

```
> update_story story_id=500_story_remove_duplicate_pty_debug_log_lines description="..."
Error: Section '## Description' not found in story file.
```

## Acceptance Criteria

- [ ] update_story.description succeeds whether or not the target story has a pre-existing ## Description section
- [ ] When the section is missing, it is created at a consistent location (between ## User Story and ## Acceptance Criteria)
- [ ] When the section exists, the existing replace-content behaviour is preserved (no regression)
- [ ] Unit test covering both: section-exists path AND section-missing path
- [ ] Symmetric fix for update_story.user_story (if it has the same brittleness)
- [ ] Error messages for genuine failure modes (file not found, write failed) are still distinct from the now-silent missing-section case

## Out of Scope

- TBD
