ws-refine
Mid-flight adjustment — incorporate learning, restructure tasks, or defer. Orchestrates review on affected artifacts.
- License 许可
- MIT
- 最近更新
- 2026-10-06
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- ws-refine
- description
- Mid-flight adjustment — incorporate learning, restructure tasks, or defer. Orchestrates review on affected artifacts.
03 SKILL.md 正文
ws.refine
Load shared context: ws._meta/SKILL.md — the sibling skill in the same skills directory this skill loaded from (resolves under any clone name, install location, or skills-root override). Also load: ws._meta/shaping.md, ws._meta/lifecycle.md, ws._meta/parallel-work.md, ws._meta/issue-tracking.md.
Purpose
Handle discoveries during specification or implementation. Two paths: (1) Protect focus -- capture distractions, continue current work. (2) Incorporate learning -- update specs when new info matters now. Both end same way: back to what you were doing.
When to Use
Discovery that might change specs / implementation revealed gap or contradiction / new requirement emerged mid-flight / assumption proved wrong. Also invoked passively: if AI detects drift during work, suggest /ws.refine.
Process
1. Articulate Discovery
State: "What did we learn?" / "Where from?" (implementation, conversation, external input)
2. Assess Relevance
"Does this change what we're currently doing?" Check task file(s) for [~] markers. If affected tasks are in-flight (another session), warn: "Task N is in-flight -- this change may cause conflicts with parallel work."
Discovery -> CURRENT work or FUTURE?
CURRENT -> Incorporate (Step 3a)
FUTURE -> Capture for later (Step 3b)
3a. Incorporate (Current Work)
- Identify affected levels -- Requirements / plan / tasks change? Does it ripple?
- Assess scope impact -- Minor tweak? Restructure? Scope reduction (good!) / expansion (be wary)?
- Propose specific changes -- Quote current, show proposed, explain why.
- Update artifacts with user approval.
- Review affected artifacts -- Run
/ws.review(composable mode) on changed artifacts. Catches second-order problems: fix for one gap may open another. - Restructure task list if discovery affects tasks:
- Stable task numbering (HARD RULE): Never renumber existing tasks. Completed
[x]and in-flight[~]keep their numbers. New tasks use letter suffixes: between 19 and 20, insert 19a (then 19b, 19c). - Task identity preservation: If scope movement changes task's goal beyond recognition, mark obsolete (
[OBSOLETE -- replaced by 19a]) and create new task. Task number is stable reference (commit messages, the tracker, parallel sessions). - Scope movement within reason: Subtasks/ACs may move between tasks, but each must remain closed, verifiable, valuable increment. Walking skeleton and vertical slice compliance from
/ws.3-tasksstill apply. - Review restructured list: Verify vertical slice compliance. Each task must leave project testable, wire into production, advance BDD/docs where applicable.
- Warn about in-flight interference: If restructuring affects
[~]task, warn explicitly about parallel session conflicts.
- Stable task numbering (HARD RULE): Never renumber existing tasks. Completed
- Check work-ledger alignment (resolve
ws-binding get work-ledger; seews._meta/SKILL.md§ Work-ledger binding) -- tracker bound: scope change affect the linked issue? (Summary mismatch, new slice, ACs shifted.) Update the issue or create a new one? If no reference yet, does this tip work into "committed" territory?local: the task/spec files are the record — keep them current, no external issue.
3b. Defer (Future Work)
MANDATORY: Every deferral persisted to durable artifact. Conversation-only deferral = failed refinement.
- Persist -- choose destination:
- a) Active SDD workstream (task file present): Append to Backlog section.
- b) No task file, relates to existing spec/workflow: Append "Future Work"/"Backlog" section.
- c) No task file, no related spec: record it in the work ledger immediately — a tracked issue if a tracker is bound, else a
localtask/spec entry. - d) Large enough for own workstream (spec kernel): Create
specs/<workflow-name>/seed.mdwith full context. If the item came fromspecs/_ideas.md, remove it there; the seed becomes source of truth. Do NOT create a tracker epic yet. - e) Belongs to a domain the project captures elsewhere (process/workflow observation, research note): resolve
ws-binding get discovery-captureand route by the recorded rule. Unbound → no such destination exists here; use (a)-(d). Seews._meta/lifecycle.md§ Discovery-capture binding. - For all paths: check tracker implications (comment on current issue? own issue needed?).
- Write enough context for self-explanatory reading weeks later.
## Backlog (Deferred)
- [Discovery]: [Description -- enough to act on cold]
- Source: [task, conversation, implementation detail]
- Context: [What were we doing? Connection?]
- Why deferred: [Not blocking because...]
- Impact if forgotten: [What breaks/degrades?]
- Revisit when: [Concrete condition, not "later"]
- Persisted to: [File path, tracker ID, or both]
- Verify persistence: Confirm "Persisted to [location]." Can't point to file or ticket = not finished.
- Don't chase -- return to current work.
- Note: "Captured [X] in [location]. Returning to [current task]."
Lifecycle: Deferred items revisited during
/ws.9-retro(step 5: Future Seeding). Between retros,/ws.statussurfaces backlog health.
4. Resume
"Discovery handled. Back to [what we were doing]." / "Returning to Task N..."
Output
If incorporated:
## Refinement Applied
**Discovery**: [What we learned]
**Affected**: [requirements.md / umbrella-requirements.md / plan.md / umbrella-plan.md / task file]
**Changes made**: [File]: [Summary]
**Review findings**: [Summary or "no new issues"]
**Task restructuring**: [Changes or "none needed"]
**Resuming**: [Current task/activity]
If deferred:
## Refinement Deferred
**Discovery**: [What we learned]
**Persisted to**: [Location]
**Context**: [What we were doing, why this came up]
**Reason**: [Not blocking because...]
**Impact if forgotten**: [What breaks/degrades]
**Revisit when**: [Concrete condition]
**Resuming**: [Current task/activity]
Anti-Patterns
- Discussing without persisting -- most common failure. Not in durable artifact = didn't happen.
- Chasing every discovery immediately (scope creep)
- Ignoring discoveries that should change plan (drift)
- Changes without noting them (invisible drift)
- Deferring everything (never learning)
- Large rewrites without user approval
04 同仓库更多 Skills
ws-tdd-review
Audit existing test code for quality, depth, and adherence to TDD principles.
ws-tdd-red
Phase 3 -- implement failing tests, validating assertion quality and depth.
ws-tdd-outline
Phase 2 -- tree-level test design, examining intent and approach per test.
ws-tdd-idea
Phase 1 -- forest-level test case discovery, mapping the full problem space.
ws-tdd-green
Phase 4 -- write minimal production code to make failing tests pass.
ws-tdd-meta
TDD shared context -- phased protocol, quality standards, and standing instructions for all TDD skills.