Feature Spec Author

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

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}_ — new field — 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.

Docs Adapter

The shared contract for publishing design documentation to a docs backend. Consumed by feature-spec-author, product-vision-steering, release-planner, and sprint-planner — each takes a docs: confluence | notion | ado-wiki | local input and routes its publish/query step through the abstract operations below. Authoring logic (what the document says) stays backend-agnostic; only the publish call swaps. docs: ado-wiki publishes to an Azure DevOps project Wiki (the natural docs surface when the tracker is ado). docs: local is the offline fallback for when no Confluence/Notion/ADO-Wiki MCP is available — the repo's documentation/ markdown is the published surface.

This mirrors the tracker adapter (task-executor/references/tracker-{jira,linear}.md).

Abstract operations

resolveParent() reads documentation/workflow-config.md: confluence.* (space key + section page ids) when docs: confluence, notion.* (root page id + section page ids + data-source ids) when docs: notion, ado.* (organisation + project + wikiIdentifier + a parent page path prefix) when docs: ado-wiki, and the local documentation/ folder tree when docs: local. If the config is missing for a remote backend, ask the user (Confluence space key + parent page id, Notion root page id, or the ADO project + wiki identifier) — or route them to confluence-space-manager / notion-workspace-manager to scaffold the container first. For docs: ado-wiki, ensure the project wiki exists (wiki_list_wikis; provision a code/project wiki in the ADO UI if none). For docs: local there is nothing to ask — the folders are created on demand.

Confluence implementation (docs: confluence)

Body format: Confluence storage format. Multiple specs publish as one page with H2 sub-sections or as child pages under the project parent.

Notion implementation (docs: notion)

Body format: Notion-flavored Markdown (read notion://docs/enhanced-markdown-spec for non-trivial blocks). The Notion backend prefers publishRecord for Specs and Releases (the databases notion-workspace-manager provisions), so the feature/spec index is queryable rather than a flat page tree.

Azure DevOps Wiki implementation (docs: ado-wiki)

Publishes to an Azure DevOps project Wiki via the Azure DevOps MCP (ado toolset). Wiki pages are Markdown, addressed by path (a /-delimited page tree), so the canonical section structure maps onto a path prefix (e.g. /SDD/Steering/Product).

Body format: ADO Wiki Markdown (GitHub-flavored + ADO extensions like [[_TOC_]], mermaid, ::: callouts). Multiple specs publish as one page with H2 sub-sections or as child pages under the section path.

Local implementation (docs: local)

The published surface is the repo's documentation/ tree (the same files the skills already author). There is no remote push and no MCP — publishing means writing/editing markdown files with Write / Edit.

Body format: plain GitHub-flavored Markdown. grep over documentation/ is the local equivalent of a Confluence/Notion search.

Per-skill publish mapping

Notes

• docs is inferred from documentation/workflow-config.md (which backend is

configured) when not passed; if several are configured, ask. A common pairing is docs: ado-wiki with tracker: ado. With no docs MCP available, default to docs: local.

• Tracker publishing (JIRA epics in release-planner, JIRA sprints in

sprint-planner) is a separate concern routed through the tracker adapter (task-executor/references/tracker-{jira,linear}.md), not this docs adapter.

Skill Routing Table

When writing a task in tasks.md, annotate it with the engineer skill that should implement it using _Skill: {skill-name}_. This same label drives JIRA routing (Phase 2) and sprint-executor delegation (Phase 4).

Routing guide

Rules

1. One skill per task. If a task needs two skills, split it. 2. Prefer the most specific skill. ob-engineer over python-data-engineer when BORO conventions apply. 3. Language always matches. Don't route Python code to ui-engineer. 4. UI tasks default to `ui-engineer` (extends javascript-data-engineer) unless framework-agnostic. 5. Unknown routing? Default to the generic data-engineer and flag for review.

JIRA label convention

The _Skill: python-data-engineer_ annotation becomes JIRA label skill:python-data-engineer on the ticket, so engineers and automation can filter.

Related

• skills/SKILL-ARCHITECTURE.md for the full skill taxonomy (role × mode × scope × language).