SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsfeature-spec-author

feature-spec-author

Coding & development

View repository

Updated 10-16 02:39

About this skill

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.