feature-spec-author

portability	ol-coupled
reuse	ol-platform-only
requires	["docs(confluence-mcp|notion-mcp|ado-wiki-mcp|local-filesystem)"]
name	feature-spec-author
description	Author a full feature specification — requirements, design, and tasks — for a single feature in the ol-sdd-workflow. Wraps software-architect in feature-design mode and extends it to produce all three artifacts (requirements.md, design.md, tasks.md) with three in-phase approval gates. Use when: designing a new feature that needs the full spec (requirements + design + tasks with three approval gates), breaking a feature from the development plan into implementable tasks, or re-specifying an existing feature. For design-only work (the design.md artifact alone, no requirements/tasks gates), use software-architect's Feature Design mode directly — this skill wraps that mode and adds the surrounding gates. Phase 1 of the ol-sdd-workflow orchestrator. Outputs land in documentation/specs/{feature-name}/ and on the docs surface (Confluence, Notion, ADO Wiki, or local files via the docs adapter).

Feature Spec Author

Role

You author the full specification for one feature. A feature spec is three documents, in strict order, with an approval gate between each. You delegate the design-level analysis to software-architect (feature-design mode) and wrap it with the requirements and tasks phases.

You are invoked by the ol-sdd-workflow orchestrator at Phase 1, or directly by a user or architect.

Deliverables

File	Template	Produced by	Gate
documentation/specs/{feature}/requirements.md	requirements-template.md	This skill	1a — requirements approval
documentation/specs/{feature}/design.md	design-template.md	software-architect (feature mode)	1b — design approval
documentation/specs/{feature}/tasks.md	tasks-template.md	This skill	1c — tasks approval

All three are published to the docs surface via the docs adapter (references/docs-adapter.md), selected by the docs: input (confluence | notion | ado-wiki | local, inferred from documentation/workflow-config.md if absent; defaults to local when no docs MCP is available). On Confluence: one page with H2 sub-sections (or three child pages) under the project parent. On Notion: a row in the Specs database plus a detail page. On ADO Wiki: one page with H2 sub-sections under {wikiRoot}/Specs. On local: the three documentation/specs/{feature}/ files are the published surface, plus a row in documentation/specs/index.md.

Workflow

Step 1 — Load Steering and Release Context

Read documentation/steering/product.md, tech.md, structure.md. If absent, stop and route the user back to product-vision-steering (Phase 0). A feature spec cannot be authored without steering context.

Also read documentation/releases/*/epic-map.md if any release is active. If the target feature appears in a release's epic-map, note the linked tracker epic id (JIRA/Linear key, ADO AB# Feature id, or local LOC- id) — the spec will attach to that existing epic rather than create a new one downstream.

Step 2 — Confirm Feature Scope

Confirm with the user:

• Feature name (kebab-case, e.g., licence-data-extraction)
• One-line description (or read from the release's features.md if present)
• Release epic to attach to (if a release plan exists): confirm the tracker epic id from epic-map.md
• Upstream feature dependencies
• Known constraints (deadline, scope exclusions, must-not-change areas)

Create the directory documentation/specs/{feature}/ and initialise empty files.

Step 3 — Gate 1a: Requirements

Populate requirements.md from requirements-template.md. Each requirement:

• User story: "As a [role], I want [feature], so that [benefit]"
• Acceptance criteria in EARS format ("WHEN...THEN the system SHALL...")
• Numbered so tasks can reference them later (1.1, 1.2, 2.1, …)

Include the non-functional requirements section (performance, security, reliability, usability) — cut any that don't apply.

Present to user. Gate 1a: user approves requirements before design work begins.

Step 4 — Gate 1b: Design

Invoke software-architect in feature-design mode with:

• The approved requirements
• Steering context
• Feature scope and dependencies

The software-architect skill produces design.md from design-template.md, including:

• Overview
• Steering alignment (how design follows tech.md and structure.md)
• Code reuse analysis
• Architecture diagram (Mermaid)
• Components and interfaces
• Data models
• Error handling
• Testing strategy
• BORO grounding (if OL/bclearer project)
• Identity design (if BIE domain)

Return the design to the user. Gate 1b: user approves design before task breakdown.

Step 5 — Gate 1c: Tasks

Break the design into atomic tasks using tasks-template.md. Enforce the atomic task requirements:

• File scope: 1–3 related files maximum
• Time boxing: completable in 15–30 minutes
• Single purpose: one testable outcome per task
• Specific files: exact paths to create or modify
• Agent-friendly: clear input/output

Each task must reference:

• _Requirements: X.Y_ — which acceptance criteria it fulfils (links back to requirements.md)
• _Leverage: path/to/file_ — existing code to reuse (reinforces reuse-over-reinvention)
• _Skill: {skill-name}_ — which engineer skill should implement it. Use the skill-routing table in references/skill-routing.md.

Estimate each task in hours (for the backlog in Phase 2).

Present to user. Gate 1c: user approves tasks before the spec is published and tracker tickets are created.

Step 6 — Publish

On all three gates passing:

1. Commit the three files to documentation/specs/{feature}/
2. Publish to the docs surface via the docs adapter (references/docs-adapter.md): publishPage (Confluence), publishRecord into the Specs DB + a detail page (Notion), a wiki page under {wikiRoot}/Specs (ADO Wiki), or — for docs: local — the committed documentation/specs/{feature}/ files plus a row in documentation/specs/index.md. Page structure:
   • H1: {Feature Name} — Spec
   • H2: Requirements (embed requirements.md)
   • H2: Design (embed design.md)
   • H2: Tasks (embed tasks.md)
3. If a release epic exists for this feature:
   • Update the tracker epic description to include a link to the spec page (Confluence/Notion/ADO-Wiki URL, or the repo-relative documentation/specs/{feature}/ path for local)
   • Update documentation/releases/{release}/epic-map.md — change the Spec Status column for this feature from "not specced" to "specced" (or "specced, ready for backlog")
   • Do NOT create a new epic; the spec attaches to the existing release skeleton
4. If no release plan exists: a standalone epic will be created later by the tracker's backlog skill (backlog-manager / linear-backlog-manager / ado-backlog-manager / local-backlog-manager, Phase 2)
5. Record the spec page URL (or local path) in the workflow config
6. Return to caller with links (including the release epic id if applicable)

---

Task Format with Skill Routing

- [ ] 1. Add licence columns to LegalEntities model
  - File: trade_analysis_services/common/models/legal_entities.py
  - Add 11 licence columns per spec §3
  - Purpose: Persist licence data extracted by pipeline
  - _Leverage: trade_analysis_services/common/models/base.py_
  - _Requirements: 1.1, 1.2_
  - _Skill: python-data-engineer_
  - _Estimate: 2h_

The _Skill: hint is consumed by the backlog skill (as a tracker label) and by sprint-executor (as the delegation target).

What This Skill Does NOT Do

• Does not do BORO or BIE ontology analysis — delegate to ontologist / ob-ontologist / bie-component-ontologist when needed
• Does not create tracker tickets (Phase 2 / backlog-manager / linear-backlog-manager / ado-backlog-manager / local-backlog-manager)
• Does not implement tasks (Phase 4 / sprint-executor)
• Does not refresh steering docs (Phase 0 / product-vision-steering)

References

• prompts/coding/templates/requirements-template.md
• prompts/coding/templates/design-template.md
• prompts/coding/templates/tasks-template.md
• skills/software-architect/SKILL.md (feature-design mode)
• references/skill-routing.md — skill routing table for _Skill: field
• references/docs-adapter.md — docs publish adapter (confluence | notion | ado-wiki | local), shared by the authoring skills

---

Feedback

If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.

If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.