df:spec-methodology

Implementation Spec Generator

Transform triage output and user decisions into a detailed implementation specification ready for development.

Workflow

1. Gather Input

The skill expects one of:

• Triage file path - Read from .aiwork/*/triage.md (any task folder)
• Ticket ID - Search .aiwork/*<ticket-id>*/triage.md, or fetch from Azure DevOps
• Continue from triage - Use context and task folder from just-completed triage session

Extract from triage:

• Ticket metadata (ID, title, type, assignee)
• Scope (files/components in scope)
• Dependencies identified
• Open questions
• Technical context gathered

2. Ask Clarifying Questions

Use AskUserQuestion tool to gather decisions. Organize questions into batches of 3-4 max.

Standard question categories:

Architecture Decisions

• Target location (which layer/module)
• API style (Composition API vs Options API for Vue)
• TypeScript strictness level

Dependencies

• Blocking dependencies (wait vs include vs parallel)
• Shared code ownership

Implementation Approach

• Migration strategy (in-place vs move)
• Compatibility layer needs (re-exports, aliases)
• Library choices (keep vs replace)

Process

• PR strategy (single vs multiple)
• Testing requirements
• Manual QA scope

Mark questions that need team input (can't be answered by assignee alone).

3. Explore Technical Details

If not already done in triage, use Explore agent to gather:

• Current component structure and props/interfaces
• Consumer files (who imports these components)
• Related patterns in codebase
• Existing tests

4. Generate Spec

Output location: If the project defines an .aiwork/ folder protocol (e.g., naming conventions, frontmatter, folder structure), follow that protocol. Otherwise use these defaults:

Write to .aiwork/{date}_{slug}/spec.md

Where:

• {date} = current date as YYYY-MM-DD
• {slug} = with ticket ID: <ticket-id>-<slugified-title>, without: <slugified-title>

If a task folder already exists (from triage or otherwise), place spec.md in the same folder.

Use the template from ${CLAUDE_SKILL_DIR}/assets/spec-template.md.

Question Templates

Architecture Questions

"Where should <component> live after migration?"
Options:
- "<layer-a> (Recommended)" - <rationale>
- "<layer-b>" - <rationale>
- "Keep in current location" - <rationale>

Dependency Questions

"Should <dependency> be completed first, or included in this task?"
Options:
- "Wait for <ticket>" - Block until dependency completes
- "Include in this task" - Expand scope to include it
- "Parallel work OK" - Proceed independently, coordinate later

Implementation Questions

"<Technology> approach?"
Options:
- "<Option A> (Recommended)" - <rationale>
- "<Option B>" - <rationale>

Tips

• Front-load blocking questions - get team-decision items identified early
• Generate dependency graph even for simple tasks - makes order explicit
• Include code snippets for non-obvious transformations
• List ALL consumer files - prevents forgotten import updates
• Keep "Noted Improvements" separate - avoids scope creep
• Acceptance criteria should be checkboxes - easy to verify completeness