Refresh Story

---
name: refresh-story
description: >
  This skill should be used when the user says "refresh the project story", "update the project story",
  "the story is stale", "regenerate the project narrative", "refresh project-story.md", "update
  PROJECT-STORY.md", "sync the story with the docs", "the story drifted", or wants an existing
  project-story file regenerated in place against the current canonical doc set. Detects which
  sections of the existing story have drifted from canonical source (vision.md, decisions/,
  planning/current.md, status.md, roadmap.md) and rewrites only those sections, preserving the user's
  edits in sections whose source is unchanged.
argument-hint: "[path to existing story file]"
user-invocable: true
allowed-tools: Read Glob Bash Write Edit
---

# Refresh Story — In-place update of an existing project-story file

You are refreshing an existing project-story file in place. The source-of-truth is the canonical doc set (`docs/vision.md`, `docs/decisions/*.md`, `docs/planning/current.md`, `docs/status.md`, `docs/roadmap.md`). The story file is a *derived view* of those docs — when the source drifts, the story must catch up.

The key discipline: **regenerate only the sections that drifted; preserve the user's edits in sections whose source is unchanged.** The story is partially user-curated prose; don't clobber the user's work without cause.

## What this skill is — and what it isn't

**This skill produces:**
- An updated version of an existing project-story file
- A footer noting what changed and why
- A short summary surfaced to the user

**This skill does NOT:**
- Generate a story from scratch (that's `/project-story`'s job)
- Modify the canonical doc set (those are `/plan`'s job)
- Overwrite sections whose underlying source is unchanged
- Add or remove sections from the structure unless source materially changed shape

## Workflow

### Step 1: Find the story file

If the user passed a path, use it. Otherwise:

- Check `PROJECT-STORY.md` at repo root
- Check `docs/story.md`
- Check `docs/project-story.md`

If none exist, this skill can't proceed — point at `/project-story` to create one first.

### Step 2: Parse the existing story

Read the story file. Identify each section:

- H2 heading text
- Section body (prose between this H2 and the next)
- Any "Generated by /rad-planner:project-story" footer (date stamp)

Build a structured representation in memory: `{section_heading: section_body, ...}`.

### Step 3: Compare claims to current canonical state

For each section, identify the corresponding canonical source:

| Section heading pattern | Canonical source |
|---|---|
| "What X is, in one line" | `vision.md` product statement |
| "Two phases, one product" / "Product shape" | `vision.md` product structure / `architecture.md` |
| "Who it's for (in build order)" | `vision.md` target users |
| "What X is explicitly NOT" | `vision.md` non-goals |
| "How the money works" | `roadmap.md` tiers / `vision.md` business model |
| "What we decided" | `decisions/*.md` |
| "Where we are right now" | `status.md` |
| "What's next" | `planning/current.md` + `roadmap.md` Next |
| "What the user will actually see when it ships" | `architecture.md` user flow |
| "What's not done yet" | `planning/current.md` open items + `roadmap.md` Later |
| "The bottom line" | synthesis — re-derive |

For each section + its source, compute a drift signal:

1. **Git mtime check**: has the canonical source been modified since the story's footer date?
2. **Content check**: do the substantive claims in the story still match the source?
   - For one-liners: exact string match (after normalizing whitespace)
   - For non-goals: are all current non-goals from `vision.md` represented?
   - For decisions list: are all decision records of the past 30 days represented?
   - For "where we are right now": does it match `status.md`'s most recent state?
3. **Section structure check**: does the canonical source still support this section, or has the project shape changed (e.g., new tier added, milestone shipped)?

Classify each section:

- **Fresh** — source mtime ≤ story mtime AND content matches
- **Drift-content** — content has diverged (regenerate)
- **Drift-structure** — section structure no longer matches source (regenerate with new structure)
- **Source-removed** — canonical source for this section is gone (flag for user review; don't auto-delete)

### Step 4: Regenerate drifted sections

For each section classified as `Drift-content` or `Drift-structure`:

1. Pull current source content from canonical docs
2. Synthesize into plain-English prose (same rendering rules as `/project-story`)
3. Replace the section body in the story

For each section classified as `Fresh`: leave the user's content alone.

For each section classified as `Source-removed`: surface to user with options:

```
Section "{heading}" — canonical source is no longer present in docs/.

  1. Remove the section
  2. Keep as-is (the user's content stays even though source is gone)
  3. Mark with "[stale: source removed YYYY-MM-DD]" note inline
```

Don't auto-delete sections — user content is partially curated.

### Step 5: Update the footer

Replace any existing "Generated by /rad-planner:project-story on YYYY-MM-DD" footer with:

```
*Generated by /rad-planner:project-story on {original-date if found, else "unknown"}.
Refreshed by /rad-planner:refresh-story on {today}: changes since last write — {comma-separated list of section headings that were regenerated}.*
```

If no original footer was found (the story file was hand-curated from the start or footer was stripped), add the refresh footer as a new addition at the end of the file.

### Step 6: Write the file in place

Write the updated content back to the same path. Preserve any user-added sections that don't match the canonical-source mapping table — those are intentional additions, leave them alone.

### Step 7: Surface the diff summary

After writing, surface to the user:

```
Story refreshed: {path}

Sections regenerated: {count} — {list}
Sections unchanged (your edits preserved): {count} — {list}
Sections needing your attention: {count} — {list with reason}

If you want to inspect what changed, run: git diff {path}
```

Be specific. If `Where we are right now` regenerated because `status.md` was updated 3 days after the story, say so explicitly.

## Rendering rules

Same as `/project-story`:
- Plain English
- No marketing language / superlatives / sensational framing
- Grounded in source — every regenerated claim traceable to a canonical doc
- Match the voice of the original story where possible (don't change tone arbitrarily on regenerated sections)
- Don't expand or compress section length without cause

## Edge cases

**The story file is missing required structure.** If the story doesn't have the section pattern this skill expects (no H2 headings, or completely freeform prose), prompt the user:

```
This story doesn't match the standard /project-story structure. Three options:

  1. Treat it as freeform — regenerate the whole file from canonical docs
  2. Try to reverse-engineer sections — best-effort parse based on prose breaks
  3. Cancel and edit the file manually
```

**No canonical docs have changed.** If every section classifies as Fresh, write nothing and surface:

```
Story is up-to-date. No canonical docs have changed since {original-write-date}.
  vision.md     last modified: {date}
  status.md     last modified: {date}
  current.md    last modified: {date}
  decisions/    most recent:   {date}

No refresh needed.
```

**The user has heavily edited the story.** If a section's content is structurally very different from what `/project-story` would produce (paragraphs reorganized, custom subheadings added, hand-written context paragraphs), classify as `Drift-content` cautiously and surface the conflict before regenerating:

```
Section "{heading}" — source has drifted AND you've made substantial edits.

  1. Regenerate from source (your edits will be replaced; keep a copy first)
  2. Preserve your version (note source drift as a known mismatch)
  3. Show me the diff and let me decide
```

## Cross-plugin notes

- This skill reads `docs/` written by rad-planner's `/plan` workflow. It does not write to those docs.
- Pairs with `/project-story` for initial creation.
- For non-rad-planner-shaped projects, the future `rad-explain` plugin will provide a more flexible version.

## Output contract

- Same file at same path, updated in place
- Original sections that haven't drifted are preserved verbatim
- Drifted sections regenerated
- Footer updated with refresh date + list of regenerated sections
- Concise diff summary surfaced to user