docs(skills): deft-roadmap-refresh transparency, PR phase, cleanup rules (#168, #174, #196)

[MScottAdams]

Summary

Updates skills/deft-roadmap-refresh/SKILL.md with three documentation improvements:

Changes

1. Analysis comment transparency (deft-roadmap-refresh skill: add rule to confirm analysis comment posting to user #168, t2.7.1): Added ! rule to Phase 2 Step 4 requiring the agent to confirm to the user that an analysis comment was posted -- includes the issue number and a direct link to the comment.

2. Phase 4 -- PR & Review Cycle (deft-roadmap-refresh skill: add review cycle step after PR push #174, t2.7.2): Added new Phase 4 after Phase 3 Cleanup. Workflow: ask user confirmation -> run pre-flight checks (CHANGELOG, task check, PR template) BEFORE pushing -> commit/push/create PR -> automatically hand off to skills/deft-review-cycle/SKILL.md.

3. Explicit cleanup convention (deft-roadmap-refresh skill: clarify cleanup convention — remove from phase body, do not strike through in place #196, t2.7.3): Replaced ambiguous Phase 3 instruction ("Strike through or move") with explicit rules: remove entries from phase body entirely (Completed section is the sole record), strike through in Open Issues Index with 'completed -- YYYY-MM-DD', added anti-pattern against duplicate records.

Tests

Added 12 tests to ests/content/test_skills.py covering deft-roadmap-refresh existence, RFC2119 legend, transparency rule, Phase 4 structure, and cleanup conventions.

Validation

• task check passes (885 passed, 25 xfailed)

PR Checklist

• SPECIFICATION.md has task coverage (t2.7.1, t2.7.2, t2.7.3)
• CHANGELOG.md has entries under [Unreleased]
• task check passes
• /deft:change N/A (<3 file changes in scope)

Closes #168, Closes #174, Closes #196

[greptile-apps]

Greptile Summary

This PR adds three documentation improvements to skills/deft-roadmap-refresh/SKILL.md: a transparency rule confirming analysis comment posting (with issue number and link), an explicit Phase 3 cleanup convention replacing the ambiguous "strike through or move" instruction, and a new Phase 4 covering the PR & Review Cycle workflow with pre-flight checks and automatic handoff to deft-review-cycle. Twelve tests are added to validate all three changes against their spec tasks (t2.7.1–t2.7.3).

• The Phase 3→4 transition uses ~ (SHOULD) instead of ! (MUST) — since Phase 4 has its own user-confirmation gate, the transition signal should be mandatory to prevent agents from silently skipping the phase.
• Phase 4 is positioned after the appendix-style sections (Analysis Comment Template, Commit Strategy, Anti-Patterns), which risks agents treating it as out-of-scope; moving it immediately after Phase 3 would make the sequential flow unambiguous.

Confidence Score: 5/5

Safe to merge; all findings are P2 style/structure suggestions that do not block correct operation.

Both findings are P2: the ~ vs ! transition is a soft signal concern (Phase 4's own ! gate limits the blast radius), and the Phase 4 placement is a structural preference. No logic errors, data issues, or security concerns were identified. Tests pass and CHANGELOG entries are well-formed.

skills/deft-roadmap-refresh/SKILL.md — minor structural and signal-strength concerns around the Phase 3→4 transition.

Vulnerabilities

No security concerns identified. Changes are limited to documentation/skill workflow instructions with no code execution, credential handling, or data access.

Important Files Changed

Filename	Overview
skills/deft-roadmap-refresh/SKILL.md	Three targeted additions (transparency rule, Phase 4 PR workflow, explicit cleanup convention) are well-formed; minor structural concerns: the Phase 3→4 transition uses ~ (SHOULD) instead of ! (MUST), and Phase 4 is placed after appendix-style sections rather than immediately after Phase 3.
tests/content/test_skills.py	12 new tests cover all three specification tasks (t2.7.1–t2.7.3); string-containment approach is consistent with the rest of the test suite and the assertions are tight enough to enforce the documented requirements.
CHANGELOG.md	Three well-formed [Unreleased] entries added, correctly referencing issue numbers and spec tasks (t2.7.1–t2.7.3); no issues found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    P0[Phase 0 — Branch Setup] --> P1[Phase 1 — Discovery]
    P1 --> P2[Phase 2 — One-at-a-Time Triage]
    P2 --> S1[Step 1: Fetch Issue Details]
    S1 --> S2[Step 2: Analyze]
    S2 --> S3[Step 3: Wait for User Decision]
    S3 -->|approved| S4[Step 4: Apply]
    S4 --> S4a["! Post analysis comment to GitHub issue"]
    S4a --> S4b["! NEW: Confirm to user — issue # + direct link"]
    S4b --> S4c[Update ROADMAP.md + Open Issues Index]
    S4c -->|more issues| S1
    S4c -->|all done| P3
    P3[Phase 3 — Cleanup] --> C1["! Remove entry from phase body entirely"]
    C1 --> C2["! Strike through row in Open Issues Index with 'completed -- YYYY-MM-DD'"]
    C2 --> C3["! Move closed issues to Completed section"]
    C3 --> T{"~ Proceed to Phase 4? (should be !)"}
    T -->|yes| P4[Phase 4 — PR and Review Cycle]
    P4 --> PF1["! Ask user: Ready to commit and create a PR?"]
    PF1 -->|confirmed| PF2["Pre-Flight: CHANGELOG + task check + PR template"]
    PF2 --> PF3["Commit / Push / Create PR"]
    PF3 --> PF4["! Sequence into deft-review-cycle/SKILL.md"]

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: skills/deft-roadmap-refresh/SKILL.md
Line: 96

Comment:
**Weak transition signal may allow agents to skip Phase 4**

The transition to Phase 4 is marked `~` (SHOULD), meaning an RFC2119-compliant agent can legitimately skip it. Since Phase 4 already contains its own `!` user-confirmation gate ("Ready to commit and create a PR?"), the user-consent concern is handled there — the transition itself should be mandatory so no agent silently omits the phase.

```suggestion
! When cleanup is complete, proceed to Phase 4 -- PR & Review Cycle.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: skills/deft-roadmap-refresh/SKILL.md
Line: 133-159

Comment:
**Phase 4 positioned after appendix sections**

Phase 4 appears after the Analysis Comment Template, Commit Strategy, and Anti-Patterns sections — sections that read like supporting reference material rather than workflow steps. An agent scanning the document sequentially may treat everything after Phase 3 as appendix content and stop before reaching Phase 4. Moving Phase 4 immediately after Phase 3 (before the template/strategy/anti-pattern blocks) would make the sequential flow unambiguous.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (3): Last reviewed commit: "docs(skills): update deft-roadmap-refres..." | Re-trigger Greptile}

[MScottAdams]

Rebase-only force-push onto updated master (added #159/#81 squash merge). No logic changes -- CHANGELOG.md conflict resolved by keeping all entries. Re-triggering Greptile.