ijfw-milestone-summary

Produce an onboarding doc for someone joining mid-stream. Output: .planning/<milestone>/SUMMARY.md.

Domain-agnostic: "what shipped" means chapters drafted for a book, launches that landed for a campaign, features released for software, episodes recorded for a podcast. Adapt the noun to the project type.

Step 1 -- Resolve milestone

Argument is the milestone slug (e.g. 1.5.0, q2-launch, book-draft-2). If absent:

1. Read .ijfw/state/workflow.json -- use the current milestone field.
2. Else read .planning/ROADMAP.md -- pick the active milestone.
3. Else list directories under .planning/ and ask which one.

Set MS="<resolved-slug>". Set OUT=".planning/${MS}/SUMMARY.md".

Step 2 -- Inventory artifacts

Read whatever exists, skip whatever doesn't. Missing files are normal -- the doc adapts.

• .planning/ROADMAP.md -- scope, dates, status of each item.
• .planning/${MS}/SUMMARY.md -- prior version (overwrite guard, see Step 6).
• .planning/${MS}/**/SUMMARY.md -- per-item outcomes.
• .planning/${MS}/**/LEARNINGS.md -- per-item decisions (written by ijfw-extract-learnings / C06).
• .planning/${MS}/**/VERIFICATION.md -- gaps, deferred items.
• CHANGELOG.md -- the ${MS} entry if present.
• Git log for the milestone tag range:
  • If v${MS} tag exists: git log --oneline v${MS} and git log v${MS}~1..v${MS} --stat.
  • Else: git log --since="<earliest .planning/${MS}/ commit date>" --oneline.
  • Else: skip git stats.

Step 3 -- Synthesize

Compose the doc with these six sections in this order. Plain English. No jargon a new contributor wouldn't know.

What shipped

One paragraph, 3-5 sentences. Lead with the user-visible outcome ("v1.5.0 shipped runtime honesty + pluggability completion -- the workflow now self-audits, dispatches parallel subagents, and runs cross-model critique unattended"). Avoid implementation detail. Adapt the noun:

• software: features shipped
• book: chapters drafted, edits landed
• campaign: launches that landed, channels lit up
• podcast: episodes recorded and published
• research: papers drafted, experiments concluded

Scope shipped

Table of items in the milestone -> outcome. Pull item names from ROADMAP.md scope list; pull outcomes from per-item SUMMARY.md one_liner (fall back to first H1 sentence). Status column: done | partial | deferred.

| Item   | Outcome                          | Status   |
|--------|----------------------------------|----------|
| <name> | <one-liner>                      | done     |

Scope deferred

List items that were planned but cut. For each: name, one-line rationale (from LEARNINGS.md "deferred" sections, RETROSPECTIVE.md, or VERIFICATION.md gaps), and where it lives next (v<next> backlog, indefinitely parked, etc.).

If nothing was deferred: say so in one line. Do not pad.

Key decisions

Aggregate from per-item LEARNINGS.md. For each decision: one-line restatement + link to the source file. Format:

- **<decision>** -- <one-line rationale>. See [<phase>/LEARNINGS.md](<relative-path>).

Top 5-7 only. If LEARNINGS.md files are absent (C06 hasn't run), fall back to CONTEXT.md or SUMMARY.md "decisions" sections; if neither, list the empty section with a one-line note "decisions log not captured for this milestone".

Known gaps / followups

From VERIFICATION.md gaps, RETROSPECTIVE.md "what to improve", and any open issues tagged with the milestone. Each item: one line, with severity if obvious (blocking | annoying | nice-to-have).

How to continue

One paragraph for someone picking up next. Cover: (1) where to start reading next (next milestone's ROADMAP or active HANDOFF), (2) the single command/skill to invoke (/ijfw-workflow, /gsd-new-milestone, etc.), (3) any state file they should load. End with one sentence on the next milestone's working title if known.

Step 4 -- Stats footer (only if git data available)

Append after the six sections:

---
Timeline: <start-date> -> <end-date> (<duration>)
Commits:  <N>
Files:    <N> changed (+<ins> / -<del>)
Authors:  <comma-separated list>

Skip silently if no tag and no date range could be determined.

Step 5 -- Length & tone gate

Cap at ~400 lines of output markdown. If a section runs long, summarize and link to the source artifact rather than inlining. Tone is operator-direct: facts first, no celebration, no hedging. Adjectives must earn their keep.

Step 6 -- Write & commit

If ${OUT} already exists and the caller did not pass --overwrite:

• Standalone invocation: ask the user SUMMARY.md exists for ${MS}. Overwrite or view existing?
• Invocation from ijfw-complete-milestone (C04): overwrite without prompt -- the milestone is closing and the summary must reflect final state.

Write the file. Then commit on the current branch:

git add ".planning/${MS}/SUMMARY.md"
git commit -m "docs(${MS}): milestone summary for onboarding"

Step 7 -- Output to caller

Print the resolved path and a 3-line excerpt of "What shipped" so the calling skill (or user) can verify the result inline without re-reading the file.

Wrote: .planning/${MS}/SUMMARY.md
What shipped: <first 3 lines of the section>

Notes

• Standalone-runnable: works without a parent skill in context.
• Called by ijfw-complete-milestone (C04); also runnable by hand any time after a milestone is mostly done.
• Pulls from C06 output (per-phase LEARNINGS.md). If C06 hasn't run, the "Key decisions" section degrades gracefully.
• Domain-agnostic: never assume software. Detect from PROJECT.md / brief / file types and adapt the noun.
• This skill writes one doc and stops. It does NOT archive the milestone, advance state, or tag releases -- those belong to ijfw-complete-milestone.