| name | technical-spec-generation |
| description | Generate technical specifications from approved functional specs (Azure DevOps Epic hierarchies) and publish as wiki pages. Use after functional approval to create implementation-ready technical documentation. |
| argument-hint | Provide the Epic ID to generate a technical specification for, or ask to review/update an existing tech spec. |
Technical Spec Generation
When to Use
- Generate tech spec from approved functional spec
- Update tech spec after functional revisions
- Review existing tech spec before implementation
Required Caller Configuration
The calling agent must provide:
- Azure DevOps organization
- Azure DevOps project
- Wiki identifier
- Azure DevOps base URL
Use these values for all MCP calls, wiki publishing, and link generation. This skill defines generic generation rules only; do not hardcode repository-specific Azure DevOps targets here.
Prerequisites
- Epic is
Active + has approval comment + no review:ready tag
- Project wiki exists using the caller-provided wiki identifier (manual one-time setup: Azure DevOps → Project → Wiki → Create project wiki)
Functional Input
| Type | Canonical fields |
|---|
| Epic | Description |
| Feature | Description (includes embedded AC) |
| User Story | Description + Microsoft.VSTS.Common.AcceptanceCriteria |
Templates (canonical, user-editable)
| Artifact | Format | Path |
|---|
| Tech spec wiki page | Markdown | .github\skills\technical-spec-generation\templates\technical-spec.md |
| Link comment | Markdown | .github\skills\technical-spec-generation\templates\tech-spec-link-comment.md |
| Regeneration summary | Markdown | .github\skills\technical-spec-generation\templates\regeneration-summary-comment.md |
Rules: load template first; preserve metadata block + heading order; reject output with unresolved placeholders.
Workflow
- Validate preconditions: Epic
Active, has approval comment, no review:ready. If techspec:stale, warn and proceed only on confirmed understanding.
- Pull hierarchy: fetch Epic (ID, title, description, state, tags, comments), child Features (Description), and each Feature's Stories (Description + AC). Build structured hierarchy.
- Analyze & design: identify architecture decisions, components, data model changes, API contracts, external deps, security, test strategy per Feature. Ask clarifying questions for ambiguity. Record risks + open questions.
- Generate spec: fill every section in canonical template from hierarchy + analysis.
- Publish: path
/Tech-Specs/[Epic-ID]-[Slugified-Title] (e.g. /Tech-Specs/356-Session-Import-from-CSV). Use MCP wiki_create_or_update_page with caller-provided wikiIdentifier and project.
- Link & clear stale: add Epic comment with wiki link (link template); remove
techspec:stale; if regeneration, add second comment (regeneration template).
Versioning
- First tech spec: v1.0
- Regeneration after functional change: major bump (v2.0, v3.0)
- Editorial fixes: minor bump (v1.1, v1.2)
Regeneration (techspec:stale present)
- Fetch previous wiki content for reference.
- Diff current hierarchy vs documented.
- Confirm valid approval evidence (add refreshed approval comment if needed).
- Generate new version + note changes.
- Update wiki page.
- Add Epic comment noting version change.
- Remove
techspec:stale.
Completion Checks
- Wiki page + comments match current templates
- Wiki page exists at expected path with all sections populated
- Epic
Active + approval comment + wiki-link comment
- No
review:ready / techspec:stale remaining
- No placeholder text in wiki page
