functional-spec-authoring

name	functional-spec-authoring
description	Guide iterative authoring of functional specifications as Azure DevOps work item hierarchies (Epic → Feature → User Story). Use for business requirement capture, scope definition, acceptance criteria, and approval readiness.
argument-hint	Describe the business need or feature idea to explore, or provide an existing Epic ID to refine.

Functional Spec Authoring

When to Use

• Define a new capability as Epic → Feature → User Story
• Iterate requirements before technical spec
• Prepare a spec for review or approval

Required Caller Configuration

The calling agent must provide the Azure DevOps organization, project, and any other target-specific values needed for MCP calls. This skill defines generic field, template, and workflow rules only; do not hardcode repository-specific Azure DevOps targets here.

Hierarchy

Level	Purpose	Azure DevOps type
Epic	WHY — business justification, strategic goal	Epic
Feature	WHAT — capability scope, boundaries	Feature (child of Epic)
User Story	WHAT — user-facing behavior, criteria	User Story (child of Feature)

Tasks/Bugs are implementation, not functional spec.

Field Model

Type	Description field	Acceptance Criteria field
Epic	business justification, success criteria, scope, stakeholders, constraints	not used
Feature	capability, value, scope, dependencies, embedded acceptance criteria	not used
User Story	story statement, UI/UX notes, data rules, edge cases	Given/When/Then (Microsoft.VSTS.Common.AcceptanceCriteria)

Description = HTML. Comments/wiki = markdown.

Templates (canonical, user-editable)

Artifact	Format	Path
Epic Description	HTML	.github\skills\functional-spec-authoring\templates\epic-description.html
Feature Description	HTML	.github\skills\functional-spec-authoring\templates\feature-description.html
User Story Description	HTML	.github\skills\functional-spec-authoring\templates\user-story-description.html
User Story AC	plain text	.github\skills\functional-spec-authoring\templates\user-story-acceptance-criteria.txt

Rules: load template before generating; preserve section headings/order; reject output with unresolved placeholders; if template conflicts with field model, STOP and ask.

State model, tags, transitions → see spec-lifecycle-management skill.

Authoring Workflow

Key principle: create NO Azure DevOps items until user approves Phase 4 preview.

Phase	Action	Create items?
1 Discovery	Gather need; draft Epic in-chat per template	No
2 Feature Decomposition	Identify capabilities; draft Features; confirm boundaries	No
3 Story Definition	Decompose into stories + G/W/T; confirm clarity	No
4 Preview + Approval	Show full hierarchy; on approval create Epic → Features → Stories in New	Yes
5 Review Readiness	Verify all fields populated; add review:ready to Epic	—
6 Approval	On stakeholder sign-off: remove review:ready, move Epic+children New → Active, add approval comment	—

Preview format:

**Epic**: [Title]
[1–2 sentence summary]
  **Feature 1**: [Title] — [scope]
    - User Story 1.1: [Title] — G/W/T summary

Approval comment: .github\skills\spec-lifecycle-management\templates\approval-comment.md. Approval unlocks tech spec generation.

Iteration Rules

Change	Action
Refine Story	Update Description/AC + comment reason
Split Story	New child Stories; mark original removed or cross-reference
Add Feature	Create child of Epic + its Stories
Remove Feature	State → Removed + comment
Post-approval scope change	Move affected items to New, drop review:ready, add techspec:stale if tech spec exists

Quality Gates (ready for review)

• Epic Description has justification, success criteria, scope
• Every Feature Description has capability, value, scope, dependencies, AC
• Every User Story Description complete
• Every User Story AC field populated with G/W/T
• Artifacts match current template files
• No [TODO]/[TBD]/empty sections
• In Scope / Out of Scope explicit

Decision Points

• Vague idea → ask clarifying questions before creating Epic
• Feature > 8 Stories → consider split
• Ambiguous AC → ask for examples
• Scope creep during iteration → flag to user

Completion Checks

• Epic + Features + Stories exist with parent-child links
• Feature AC in Description; User Story AC in AC field
• Hierarchy is New+review:ready OR Active+approval comment
• No placeholder text remains