feat: add /vault-cli:refine-task slash command

[bborbe]

Summary

• New /vault-cli:refine-task <id> slash command that conversationally refines task substance: invokes task-auditor, translates findings into numbered questions (max 3/turn, no either/or), applies user answers, re-audits, loops until score ≥ 8.
• Reuses existing task-auditor agent for read-only judgment; refine-task is the write-back wrapper.
• Cross-refs added from work-on-task and create-task so the refinement step is discoverable in the task lifecycle.

Why

Today /vault-cli:work-on-task is content-agnostic by design — it sets status and finds guides, it does not question task substance. When a task isn't ready (weak DoD, vague subtasks, scope creep, goal-orphan), there's no purpose-built path to fix it: audit-task is read-only; no improve-task skill in vault-cli; grill-me is generic without write-back. refine-task fills the gap between create-task (first draft) and work-on-task (start work).

Test plan

• Dogfooded on a known-weak task (the very task that spawned this skill) — auditor flagged 3 majors + 4/7 scope smells, score 5/10
• Applied 3 numbered-question answers (drop orphan goal link, rename # Items → # Tasks, add Definition of Done)
• Re-audit confirmed score 5 → 8 (Good)
• make precommit green (mods, format, tests, lint, vet, vulnerability scans, license headers)
• Cross-refs visible in commands/work-on-task.md + commands/create-task.md (verifiable via grep)

[ben-s-pull-request-reviewer]

I already have the full diff content. Let me analyze it directly.

Based on the diff I captured, here is my review:

---

PR Review: feat: add /vault-cli:refine-task slash command

Files Changed

• CHANGELOG.md — Added unreleased section
• README.md — Added command to table
• commands/create-task.md — Cross-reference added
• commands/refine-task.md — New 86-line slash command (main implementation)
• commands/work-on-task.md — Cross-reference added

---

Automated Checks

License file: Present (from repo baseline).

make precommit: Not run — the diff touches only markdown command files (.md), not Go code. make precommit runs Go linting/formatters/tests which are not applicable to this change. This is acceptable for a pure documentation/command-descriptor PR.

---

Findings

Must Fix (Critical)

None.

Should Fix (Important)

None.

Nice to Have (Optional)

1. commands/refine-task.md:8 — allowed-tools includes Bash but the command description shows no Bash invocation. The process steps (validate, auditor, surface gaps, apply, re-run) are all done via Task/Read/Edit/Glob/AskUserQuestion. Either remove Bash from allowed-tools or add a step that legitimately uses it (e.g., "validate the task file exists" via Bash ls).

2. commands/refine-task.md — The Glob pattern 24 Tasks/*<arg>*.md is hardcoded. If the vault root from config.yaml is different (e.g., Tasks/ instead of 24 Tasks/), the glob will silently fail to find files. Consider noting this assumption, or using a more generic pattern like *<arg>*.md and letting the user narrow if needed.

---

Concerns Addressed (from plan)

Concern	Status
Loop condition score < 8 AND remaining gaps are addressable — termination reliable?	Addressed — loop exits via two escape hatches: score ≥ 8, or remaining gaps need decisions outside the loop's scope (⚠ Task improved to X/10. Remaining: <bullets>. Re-run when ready.)
Edit calls target correct file?	Addressed — step 1 validates and resolves the path; all subsequent Edit calls use the same resolved path
Bash in allowed-tools but not used?	Raised as nit — should remove or justify inclusion
Hardcoded 24 Tasks/*<arg>*.md glob pattern?	Raised as nit — noted as vault-configuration-dependent
No test file for new command?	Not a gap — slash command .md files are documentation/descriptors; no Go test applicable. The claim "make precommit green" refers to the overall project precommit, which lints Go code (not markdown command files).

---

Manual Review Summary

The command is well-structured:

• Input validation is thorough (no arg, path-like vs name-like, multiple/zero matches)
• Reuses task-auditor subagent rather than duplicating audit logic (good separation)
• Conversational UX is respected: 3 questions max per turn, AskUserQuestion with numbered options, (Recommended) lead
• Loop has clear exit conditions
• Cross-references in create-task.md and work-on-task.md are correctly placed

Verdict: approve — no critical or important issues found.

---

{
  "verdict": "approve",
  "summary": "New slash command adds solid task-refinement workflow reusing the existing task-auditor subagent. No critical or important issues found; two nits raised around Bash being listed in allowed-tools without being used, and the hardcoded Glob pattern being vault-configuration-dependent.",
  "comments": [
    {
      "file": "commands/refine-task.md",
      "line": 8,
      "severity": "nit",
      "message": "allowed-tools includes 'Bash' but the command process shows no Bash invocation (only Task, Read, Edit, Glob, AskUserQuestion). Either remove Bash or document where it's used."
    },
    {
      "file": "commands/refine-task.md",
      "line": 23,
      "severity": "nit",
      "message": "Glob pattern '24 Tasks/*<arg>*.md' is hardcoded and vault-configuration-dependent. If the vault root from config.yaml differs, the glob will silently fail to find tasks."
    }
  ],
  "concerns_addressed": [
    "correctness: Loop exit conditions (score ≥ 8 OR unresolvable gaps) provide reliable termination per commands/refine-task.md:68-72",
    "correctness: Edit calls target the resolved task file path from step 1, not other files",
    "security: Bash is listed in allowed-tools but not invoked — raised as nit rather than security issue since no execution occurs",
    "correctness: Glob pattern '24 Tasks/*<arg>*.md' is hardcoded — raised as nit; command does respect config.yaml vault root",
    "tests: Slash command .md files are documentation/descriptors, not Go code requiring unit tests"
  ]
}