triage-shaping

name: triage-shaping description: Shape and refine a wrkq task by ID. Use when given a task ID to analyze, clarify requirements, and update the task with a structured implementation approach.

Triage Shaping

Shape an existing wrkq task into a well-defined, actionable specification.

Usage

/triage-shaping <wrkq cat task> OR <task-id> <task-slug>

Process

Step 1: Fetch Task Details if not provided

if the full task was not provided, read the task by ID:

wrkq cat <task-id>

Step 2: Understand the Ask

Before shaping:

1. Read the task description thoroughly
2. Explore any referenced files or code
3. Understand the scope and constraints
4. Identify what's ambiguous or underspecified

Step 3: Context Grounding (Environment Scan)

Orient to the environment:

• Scan for existing patterns that inform reasonable defaults
• Note what's present that the proposal should integrate with
• Identify constraints the user may not have stated but likely expects

Step 4: Shape the Implementation

Apply prompt-shaping techniques:

1. Restate in natural language - Articulate what you understand the task wants, making assumptions explicit
2. Bullet the structure - Break the restatement into scannable components
3. Propose an iterative grounding loop - Define how to verify the work is complete
4. Identify decisions needed - Surface any ambiguities requiring user input

Step 5: Iterative Testing

Propose how completion will be verified:

• Define success criteria - What observable outcome proves the request is fulfilled?
• Propose a verification method - A concrete check (test, command, assertion)
• Commit to iteration - Run verification until it passes

Use fully integrated tests, not mocks.

Step 6: Present Shaped Task

Display the refined task to the user:

• Original task summary
• Shaped interpretation with explicit assumptions
• Structured breakdown of work
• Success criteria and grounding loop
• Any questions or decisions needed

Step 7: Update Task in wrkq

Once the user approves the shaped approach, offer to:

1. Update the task description with the shaped specification. Retain the original user text for full historical context:

wrkq edit <task-id>

2. Mark the task as open (ready for execution):

wrkq set <task-id> --state open

3. Add a comment documenting the shaping:

wrkq comment <task-id> "Shaped implementation approach - ready for execution"

Example

User: /triage-shaping T-00042

Claude: Let me fetch and analyze this task...

[Runs: wrkq cat T-00042]

**T-00042: Add user preferences API**
- Priority: 2
- State: draft
- Description: "Need some way to save user preferences"

This task is underspecified. Let me shape it:

---

**Shaped Interpretation:**

It sounds like you want to persist user-configurable settings. I'm assuming:
- REST API endpoints (GET/PUT /api/preferences)
- JSON storage per user
- Schema includes: theme, notifications, locale
- Authenticated users only

**Structured Breakdown:**
1. Define preferences schema/types
2. Add database migration for preferences table
3. Implement GET endpoint (fetch current)
4. Implement PUT endpoint (update)
5. Add validation middleware

**Grounding Loop (Iterative Testing):**
I'll write integration tests for both endpoints, iterating until they pass with valid auth and reject without.  I will not use mocks.

**Questions:**
- Should preferences sync across devices?
- Any specific settings beyond the defaults I listed?

---

If this looks correct, I can update T-00042 with this specification and mark it open.

Notes

• This skill shapes tasks but does NOT execute them
• The goal is to transform vague requests into actionable specifications
• Always surface assumptions explicitly
• The user decides whether to update the task or refine further