reassess-roadmap

Post-slice checkpoint. Looks at what was learned during the slice and asks whether the milestone roadmap still matches reality. Often the answer is yes -- but when it's no, catching it here is cheap; catching it at milestone-end is expensive.

When to run

• After ytstack:summarize-task closes the last task of a slice
• Before picking the next slice to plan/execute
• NOT mid-slice -- in-flight changes scatter the plan

Anti-Pattern: "The plan was right, no need to reassess"

Run it anyway. It takes 2 minutes and either confirms the plan (good -- more confidence) or surfaces a gap the next slice would have hit blind (much better -- save a slice of wasted work). The value isn't in changing the plan -- it's in knowing whether to change it.

Checklist

1. Run preamble -- detect milestone + just-completed slice
2. HARD-GATE -- slice must be fully complete (all tasks [x])
3. Summarize the slice -- show outcomes of the N task summaries
4. Ask: does the remaining roadmap still fit?
5. If no, prompt for changes -- add / split / reorder / remove slices
6. Update M###-ROADMAP.md with agreed changes
7. Append decision to M###-CONTEXT.md if the change is non-trivial
8. Update STATE.md -- flip completed slice, set next active_slice (guarded)
9. Backlog sweep (only if this was the last slice of the milestone) -- per-item prompt from M###-CONTEXT.md scope
10. Stale milestones (M018) -- for each STALE_MILESTONES entry ask dropped / shipped-informally / keep and write the state

Preamble

# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.
_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"
if [ -f "$_LIB" ]; then
  . "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null
  _PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"
else
  # Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.
  _IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)
  _PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
  _YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""
  [ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }
fi
cd "$_PROJECT_DIR" 2>/dev/null || true
_PROJECT_SLUG=$(basename "$_PROJECT_DIR")
_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)

_NON_INTERACTIVE=false
if [ -n "$YTSTACK_NON_INTERACTIVE" ] || [ -n "$OPENCLAW_SESSION" ] || [ -n "$CLAUDE_AGENT_TEAM_MEMBER" ]; then
  _NON_INTERACTIVE=true
fi

_CURRENT_MILESTONE=none; _ACTIVE_SLICE=none; _TRACKER=none
if [ -f "$_YT_DIR/STATE.md" ]; then
  _CURRENT_MILESTONE=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1)
  _ACTIVE_SLICE=$(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1)
  # External issue tracker (none | linear | github-projects | paperclip | jira)
  _TRACKER=$(sed -n 's/^tracker: *//p' "$_YT_DIR/STATE.md" | head -1)
  _TRACKER=${_TRACKER:-none}
fi

# Determine if the current slice is complete
_SLICE_PLAN="$_YT_DIR/$_CURRENT_MILESTONE-$_ACTIVE_SLICE-PLAN.md"
_SLICE_COMPLETE=no
if [ -f "$_SLICE_PLAN" ]; then
  _REMAINING=$(grep -c '^- \[ \]' "$_SLICE_PLAN" 2>/dev/null || echo 0)
  [ "$_REMAINING" -eq 0 ] && _SLICE_COMPLETE=yes
fi

# Stale milestones (M018): planned/in-progress roadmaps with no summaries and no file newer than 14 days
_STALE_MILESTONES=""
for _rm in "$_YT_DIR"/M[0-9][0-9][0-9]-ROADMAP.md; do
  [ -f "$_rm" ] || continue
  _m=$(basename "$_rm" -ROADMAP.md)
  _st=$(sed -n 's/^status: *//p' "$_rm" | head -1)
  case "$_st" in planned|in-progress) ;; *) continue ;; esac
  if command -v yt_find_artifacts >/dev/null 2>&1; then
    [ -n "$(yt_find_artifacts "$_YT_DIR" "$_m-*SUMMARY.md")" ] && continue
  else
    [ -n "$(ls "$_YT_DIR"/$_m-*SUMMARY.md 2>/dev/null)" ] && continue
  fi
  [ -n "$(find "$_YT_DIR" -maxdepth 1 -name "$_m-*.md" -mtime -14 2>/dev/null)" ] && continue
  _STALE_MILESTONES="${_STALE_MILESTONES:+$_STALE_MILESTONES }$_m"
done

echo "HAS_YTSTACK: $_HAS_YTSTACK"
echo "YTSTACK_NON_INTERACTIVE: $_NON_INTERACTIVE"
echo "CURRENT_MILESTONE: $_CURRENT_MILESTONE"
echo "ACTIVE_SLICE: $_ACTIVE_SLICE"
echo "SLICE_COMPLETE: $_SLICE_COMPLETE"
echo "STALE_MILESTONES: ${_STALE_MILESTONES:-none}"
echo "TRACKER: $_TRACKER"

Procedure

Step 2 HARD-GATE. If SLICE_COMPLETE=no: abort with "slice still has open tasks. Close them via summarize-task before reassessing."

Step 3. Collect recent summaries: read all {MILESTONE}-{SLICE}-T##-SUMMARY.md files. For each, extract Outcome + Deviations. Present to user:

Slice {CURRENT_MILESTONE}-{ACTIVE_SLICE} complete. Here's what shipped:

{For each task summary:}

• T##: {OUTCOME_FIRST_LINE} (deviations: {DEVIATIONS_SHORT})

Step 4. Use AskUserQuestion:

Given what actually shipped, does the remaining roadmap for {CURRENT_MILESTONE} still fit reality?

Look at the next slice in {CURRENT_MILESTONE}-ROADMAP.md. Does it still make sense given what you learned in this slice?

RECOMMENDATION: A if nothing surprised you. B if one or two surprises. C if you feel "we should reconsider the whole plan."

A) Yes, proceed as planned. (Completeness: 10/10) B) Partial changes needed -- add / split / reorder a slice. (Completeness: 8/10) C) Major rethink -- the milestone scope or goal shifted. (Completeness: 10/10 for doing the rethink honestly)

If A: jump to Step 8. If B: Step 5. If C: prompt "Should we go back to /ytstack:plan-milestone to re-define the milestone? The C option means the current roadmap is stale enough to rebuild." Ask user; if yes, STOP and recommend rerun. If they want to patch in place, proceed to Step 5.

Step 5. For B: use AskUserQuestion (open-ended):

What needs to change in the roadmap?

Describe changes in plain English. Examples:

• "Add a new slice S04 between S02 and S03 for rate-limiting -- surfaced during S02."
• "Remove S03 -- turns out what we did in S02 covered it."
• "Split S03 into S03a (schema change) and S03b (UI update) -- too big for one slice."

Remember as _CHANGES.

Step 6. Apply changes to {CURRENT_MILESTONE}-ROADMAP.md via Edit tool. For each change:

• Add: insert a new - [ ] S## -- {name} line at the correct position, increment total_slices frontmatter
• Split: replace one slice line with two, increment total_slices
• Remove: delete line, decrement total_slices
• Reorder: move lines (preserve checkbox state)

If slices beyond the modified ones have placeholder task lists, leave them -- slice-milestone will handle re-planning.

Step 7. If the change was non-trivial (B or C): append to {CURRENT_MILESTONE}-CONTEXT.md:

## Reassessment {ISO_TIMESTAMP}

After **{ACTIVE_SLICE}**, changed the roadmap:

{CHANGES}

Reason: {USER_REASON_IF_PROVIDED}

Step 8. Update STATE.md:

If YTSTACK_NON_INTERACTIVE is false (i.e. CLAUDE_AGENT_TEAM_MEMBER is unset):

• Flip active_slice from completed slice to the next unfinished slice (next - [ ] S## in ROADMAP), or active_slice: none if no unfinished slice remains
• active_task: none

If YTSTACK_NON_INTERACTIVE is true (running as swarm teammate): skip frontmatter writes. Log:

[ytstack:reassess-roadmap] skipping STATE.md active_slice/active_task write -- running as swarm teammate (CLAUDE_AGENT_TEAM_MEMBER set)

Regardless of teammate mode:

• Bump last_updated
• Status line: **Status:** {CURRENT_MILESTONE} -- slice {OLD_SLICE} complete. Next slice: {NEW_ACTIVE_SLICE}.

Also flip - [ ] {OLD_SLICE} → - [x] {OLD_SLICE} in {CURRENT_MILESTONE}-ROADMAP.md and bump completed_slices.

Step 9. Backlog sweep (only if this was the last slice of the milestone -- no remaining - [ ] S## in ROADMAP).

Read {CURRENT_MILESTONE}-CONTEXT.md. Extract any backlog items listed under a "Backlog" or "Deferred" heading (pattern: lines starting with - under such a heading). If none found, skip this step and report "no backlog items found." If TRACKER is not none, say once before the first item: "Issue-level work for this project is tracked in {TRACKER}; items that are BAU belong there, not in a new slice or milestone." (no extra question; the per-item A/B/C below is unchanged).

For each backlog item, use AskUserQuestion (multi-choice):

Wrapping up {CURRENT_MILESTONE} -- sweeping backlog item: "{ITEM_DESCRIPTION}"

This item was deferred into {CURRENT_MILESTONE} scope but not scheduled in any slice. Now that the milestone is done, decide its fate.

RECOMMENDATION: A if the item shipped as part of normal work. B if it is genuinely needed but needs more work. C if it no longer applies.

A) Fully shipped -- delete this item from the backlog. (Completeness: 10/10, tier: task) B) Still needed -- trim to what remains and carry forward to the next milestone's CONTEXT.md. (Completeness: 8/10, tier: task) C) Drop it -- not worth doing. Add a one-line DECISIONS.md note explaining why. (Completeness: 7/10, tier: task)

For A: remove the item from the backlog section in {CURRENT_MILESTONE}-CONTEXT.md. For B: prompt "What is still needed? (one sentence)" then update the item text in {CURRENT_MILESTONE}-CONTEXT.md and copy the trimmed item to the next milestone CONTEXT.md (append under a "Carried from {CURRENT_MILESTONE}" heading) once the next milestone exists. For C: remove the item from {CURRENT_MILESTONE}-CONTEXT.md and append to DECISIONS.md:

## {ISO_DATE}: Drop backlog item "{ITEM_DESCRIPTION}" from {CURRENT_MILESTONE}

**Context:** item was deferred into {CURRENT_MILESTONE} but not executed.
**Chose:** drop
**Reason:** {USER_REASON}

Report + return

Slice {OLD_SLICE} closed, roadmap reassessed: {A/B/C outcome}.

{If B/C:} Changes logged to {CURRENT_MILESTONE}-CONTEXT.md under "Reassessment {TIMESTAMP}".

Next: slice {NEW_ACTIVE_SLICE}. Run /ytstack:plan-task to flesh out the first task, or use subagent dispatch if available.

If this was the last slice of the milestone: flip milestone status to done in .ytstack/ROADMAP.md (global) and consider /ytstack:plan-milestone for the next milestone.

Step 10 -- Stale milestones (M018 artifact states). For each milestone in STALE_MILESTONES (status planned or in-progress, no summaries, nothing touched for 14 days), use AskUserQuestion:

Milestone {M###} has plans on disk but no execution and no activity for two weeks. What is its real state?

Leaving it planned keeps it on every dashboard as if it were next. Writing the real state makes ROADMAP.md honest and lets session-start stop flagging it.

RECOMMENDATION: B if the work happened outside the ytstack loop (direct commits, another tracker); A if nobody intends to do it; C only if it really is next.

A) dropped -- plans stay on disk, status written, global row updated. (Completeness: 10/10, tier: core) B) shipped-informally -- status written + one-line note in {M###}-CONTEXT.md about where the work lives. (Completeness: 10/10, tier: core) C) keep -- leave planned; ask again in 14 days. (Completeness: 6/10, tier: core)

Write the chosen state into {M###}-ROADMAP.md frontmatter (status:) and the matching row in the global ROADMAP.md (Edit). Never delete plan files here (ytstack:reconcile owns archiving).

Terminal State

• Return after ROADMAP + STATE + (optional) CONTEXT updates + (optional) backlog sweep
• Abort if slice not complete (Step 2 HARD-GATE)
• Abort + recommend rerun if user picks "major rethink, restart milestone"

Do NOT auto-invoke plan-task or plan-milestone.