Product Vision Steering

Product Vision & Steering

Role

You produce the three steering documents that every downstream spec, backlog item, and implementation relies on for context. These are the project's long-lived "constitution" — they change rarely and intentionally.

You are invoked by the ol-sdd-workflow orchestrator at Phase 0, or directly by the user when steering needs to be set up or refreshed.

Deliverables

The templates are bundled inside this skill at references/templates/ so they ship with the skill zip. Mirror copies exist at prompts/coding/templates/{product,tech,structure}-template.md for non-skill consumers (e.g. software-architect, ol-sdd-workflow/references/phase-flow.md) — keep the two in sync when editing.

Each filled file is also published to the docs surface (Confluence, Notion, ADO Wiki, or local files) via the docs adapter (skills/feature-spec-author/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 Notion the three pages land under 02 Steering. On ADO Wiki they land under {wikiRoot}/Steering. On local the committed documentation/steering/ files are the published surface.

Workflow

Step 1 — Detect Existing State

Check for:

• documentation/steering/ directory and each of the three files
• If any exist, read them and treat them as the baseline to refine (not replace)
• Identify codebase type from manifest files: package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, Pipfile, etc.

Step 2 — Analyse the Project

Scan the codebase for:

• Primary language(s) and version
• Frameworks and major dependencies
• Directory structure and apparent architectural style
• Naming conventions (snake_case vs PascalCase vs camelCase)
• Testing framework and layout
• CI/CD configuration

Do not fabricate details you can't verify — flag unknowns for the user.

Step 3 — Gather Product Context

Ask the user (skip questions you can answer from an existing README or docs):

• What problem does this product solve?
• Who are the primary users / consumers?
• What are the top 3–5 features that deliver value?
• What are the business or project objectives?
• What does success look like in 6 months? (metrics, milestones)
• Any known principles, constraints, or non-negotiables?

Step 4 — Fill the Three Templates

Populate each template. Keep it concrete and specific to this project — no boilerplate filler.

For tech.md, draw from software-architect/references/technology-stack.md if the project is on the bclearer/OL stack. Otherwise document the actual stack.

For tech.md's `## SDD Workflow Backends` section, record the chosen tracker (jira|linear|ado|local) and docs (confluence|notion|ado-wiki|local). Source the choice in this order: (a) the mode passed by ol-sdd-workflow's Backend Selection step; (b) documentation/workflow-config.md if already set; (c) if neither exists, ask the user now and persist it to workflow-config.md from skills/ol-sdd-workflow/references/workflow-config-template.md. This keeps the human-readable tech.md section and the machine-read config aligned — they must agree.

For structure.md, document what is there now (not an aspirational rewrite). If the structure has known problems, note them in a dedicated section but don't change it.

Step 5 — Present for Approval

Present all three filled documents to the user. Ask for approval per document — it's acceptable to approve them together, but give the user the chance to refine each.

Step 6 — Commit and Publish

On approval: 1. Write the three files to documentation/steering/ 2. Publish each to the docs surface via the docs adapter (publishPage): Confluence pages under the project parent, Notion pages under 02 Steering, ADO Wiki pages under {wikiRoot}/Steering, or — for docs: local — the committed documentation/steering/ files are the published surface (nothing more to do). For remote backends, ask for the space key + parent page id (Confluence), root page id (Notion), or wiki identifier + root path (ADO Wiki) if not configured. 3. Ensure documentation/workflow-config.md records the selected tracker and docs mode plus the per-backend ids (from skills/ol-sdd-workflow/references/workflow-config-template.md) — and that it matches the ## SDD Workflow Backends section of tech.md. These two must stay in sync. 4. Return to the caller (orchestrator or user) with links to committed files and docs pages (or local paths)

---

When to Refresh Steering

Steering docs should be stable. Refresh when:

• The product pivots (new users, new primary problem)
• The tech stack changes materially (new primary language, new framework)
• The project structure is deliberately reorganised
• Onboarding a new team member reveals that current steering is misleading

Minor drift (a new library added, a refactor) does not warrant a steering refresh — handle it in feature specs.

What This Skill Does NOT Do

• Does not design features (that's feature-spec-author)
• Does not make architecture decisions at feature-level (that's software-architect)
• Does not produce ontology models (that's ontologist / ob-ontologist)
• Does not define a phased development roadmap — that belongs on the project's docs landing page (Confluence/Notion/local) or as a follow-up to steering

References

• references/templates/product-template.md — product vision template (bundled)
• references/templates/tech-template.md — technology stack template (bundled)
• references/templates/structure-template.md — project structure template (bundled)
• prompts/coding/templates/{product,tech,structure}-template.md — mirror copies in the global prompts tree (kept in sync)
• skills/software-architect/references/technology-stack.md — bclearer/OL platform libraries reference
• skills/software-architect/references/confluence-pages.md — Confluence page conventions
• skills/feature-spec-author/references/docs-adapter.md — docs publish adapter (confluence | notion | ado-wiki | local)

---

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.

Product Overview

How to use this document. Steering doc — describes WHO the product is for and WHY it exists.

Read by every downstream phase of the OL-SDD workflow. Keep it concrete, short, and current. Avoid

aspirational marketing language; prefer specifics that constrain future decisions.

Product Purpose

[One paragraph: what problem does this product solve, and for whom? If you can't say it in 3-4 sentences, the purpose isn't sharp enough yet.]

Stakeholders

[Who decides direction; who gets called when something is on fire; who you check with on scope.]

• Product owner: [name, role]
• Technical lead: [name, role]
• Primary contact for users: [name or channel]
• Other decision-makers: [as applicable]

Target Users

[Concrete user types — not "users" or "customers" in the abstract. Include their workflow context and the pain point this product addresses for each.]

• [User type 1]: [context, pain point, success criteria]
• [User type 2]: [context, pain point, success criteria]

Key Features

[Top 3-7 features that deliver the core value. Order by importance. If everything is critical, nothing is — force the ranking.]

1. Feature 1: [Description and the user need it serves] 2. Feature 2: [Description and the user need it serves] 3. Feature 3: [Description and the user need it serves]

Business Objectives

[Why is the team investing in this? What outcome moves the business needle?]

• [Objective 1]
• [Objective 2]
• [Objective 3]

Success Metrics

[How we know the product is working. Each metric needs a target and a method of measurement.]

Product Principles

[Core principles that guide trade-off decisions. When two features conflict, these are the tiebreakers.]

1. [Principle 1]: [Explanation and what it rules out] 2. [Principle 2]: [Explanation and what it rules out] 3. [Principle 3]: [Explanation and what it rules out]

Constraints & Non-Negotiables

[Hard constraints that downstream design and implementation must respect. Distinguish carefully between "we'd prefer not to" and "we cannot".]

• Regulatory / compliance: [GDPR, HIPAA, SOC2, sector-specific]
• Technical: [must run on-prem, must integrate with X, must support offline]
• Cost / capacity: [budget ceilings, team size, deadline windows]
• Organisational: [must reuse vendor X, cannot expose data to vendor Y]

Out of Scope

[Explicit list of things this product is NOT trying to do — at least for the current horizon. Helps anchor scope discussions.]

• [Capability 1 — not in this product because X]
• [Capability 2 — deferred to phase N]

Future Vision

[Where the product is going beyond the current horizon. Mention only directions the team is actively reserving design space for — not every possible add-on.]

• [Direction 1 — what would change about the product]
• [Direction 2 — what would change about the product]

Ontological Grounding (optional)

[If the project uses BORO / BIE methodology, link the canonical domain ontology model here. Otherwise delete this section.]

• BORO domain model: [link]
• BIE component models: [link]

Project Structure

How to use this document. Steering doc — describes WHERE things live and HOW they are named.

Read by every engineer (human and AI) before placing or naming a new file. If a convention here

conflicts with an in-repo pattern, the in-repo pattern wins for already-placed code; this document

wins for new code. Update this doc when the convention changes — don't let drift accumulate.

Directory Organisation

[Describe the actual directory tree. Annotate purpose per top-level entry. Keep it current — an
out-of-date tree is misleading.]

project-root/
├── src/                    # [Purpose]
├── tests/                  # [Purpose]
├── documentation/          # [Repo-side specs and steering docs]
│   ├── steering/           # product.md, tech.md, structure.md
│   ├── releases/           # Per-release plans
│   └── specs/              # Per-feature specs (requirements/design/tasks)
├── scripts/                # [Build / utility scripts]
└── [other top-level dirs]

Naming Conventions

Files

Code Symbols

Test File Placement

[Test placement is a frequent source of inconsistency. Be explicit.]

• Unit tests: [colocated next to source / mirrored under tests/ / etc.]
• Integration tests: [location, naming convention]
• End-to-end tests: [location, naming convention — note OAS-23 standardised the e2e + thin-slice

convention; reference its prompt if applicable]

• Fixtures and test data: [location]
• Snapshots / golden files: [location]

Import Patterns

Import Order

1. Standard library / language built-ins 2. Third-party external dependencies 3. Internal project modules (absolute imports) 4. Relative imports within the same module 5. Style / asset imports

Module / Package Organisation

[Describe the canonical import style for this project — absolute from project root, relative within a module, namespace packages, etc.]

Code Structure Patterns

Module / Class Organisation

1. Module docstring (purpose)
2. Imports
3. Constants and configuration
4. Type / interface definitions
5. Main implementation
6. Helper / private functions
7. Exported public API

Function / Method Organisation

- Input validation first (fail fast at the boundary)
- Core logic
- Single clear return point where practical
- Errors raised, not silently swallowed

File Organisation Principles

• One primary class / module per file
• Related helpers may co-exist if they only serve the primary
• Public API at the top or bottom — be consistent within the project
• Internal helpers prefixed or marked clearly

Skill-to-Directory Routing (if applicable)

[When the project is built with OL-SDD engineer skills, declare which skill writes code where. Helps both sprint-executor's routing and human reviewers' expectations.]

Documentation Surface Map

[Where each kind of documentation lives. Avoids duplication between repo, Confluence, and JIRA.]

Code Organisation Principles

1. Single responsibility — each file has one clear purpose 2. Modularity — code is organised into reusable modules 3. Testability — structure makes testing straightforward 4. Consistency — follow established patterns before introducing new ones

Module Boundaries

[Define how parts of the project interact and where the firewall lines are.]

• Public API vs internal: [what is exposed]
• Stable vs experimental: [where experimental code lives]
• Platform-specific isolation: [if applicable]
• Dependency direction: [which modules may depend on which — call out the forbidden directions]

Code Size Guidelines

Override conditions: [when a function genuinely needs to exceed the ceiling — usually never. Document the rare exceptions.]

UI / Frontend Structure (if applicable)

[Delete if not relevant.]

src/
└── [ui-or-frontend-dir]/
    ├── components/        # [Atomic / Feature-Sliced / etc.]
    ├── pages-or-routes/   # [Naming convention]
    ├── state/             # [State management modules]
    └── styles/            # [CSS / theme]

Documentation Standards

• All public APIs must have documentation
• Inline comments only where the WHY is non-obvious
• README at each major module boundary
• Follow the language's idiomatic documentation conventions

Technology Stack

How to use this document. Steering doc — describes WHAT we build with. Authoritative reference

for downstream design and implementation. If something isn't here, it isn't sanctioned. Adding a

new language, framework, or major dependency requires a steering refresh, not a silent introduction.

Project Type

[One sentence: what kind of project this is — web app, CLI, library, data pipeline, agent, etc.]

Core Technologies

Primary Language(s)

• Language: [e.g. Python 3.11, Go 1.21, TypeScript 5.x, Rust 1.75]
• Runtime / compiler: [as applicable]
• Language tooling: [package manager, build tool, formatter]

Application Architecture

[One paragraph describing the high-level structural pattern: monolith, microservices, pipeline-of-stages, agent-orchestration, plugin-host, etc. Link to the architecture document if one exists.]

Key Frameworks & Libraries

[The major load-bearing dependencies. Include version constraints. Do not list every transitive dep.]

Data Storage

• Primary storage: [e.g. PostgreSQL 16, S3, files, in-memory]
• Caching: [Redis, in-process, none]
• Data formats: [JSON, Parquet, Protocol Buffers, Avro]
• Schema management: [Alembic, Liquibase, app-managed]

External Integrations

• APIs we depend on: [list with auth method per integration]
• Protocols: [REST, gRPC, WebSocket, message queue]
• Credential management: [Vault, env vars, cloud secrets manager]

Platform Libraries (if applicable)

[For projects on the OL / bclearer stack, list the platform libraries in use. See skills/software-architect/references/technology-stack.md for the canonical inventory. Otherwise delete this section.]

• Foundation: [e.g. nf_common]
• Domain: [e.g. bclearer_pdk]
• Other OL platform libs: [as applicable]

Allowlist & Discouraged Libraries

[Governance: which libraries we deliberately do or do not use. New libraries outside the allowlist require a steering refresh discussion.]

Allowlist

• [Library / category — approved use cases]

Discouraged / forbidden

• [Library / category — reason; what to use instead]

Tooling by Lifecycle Stage

SDD Workflow Backends

The Spec-Driven Development workflow (ol-sdd-workflow) runs against a chosen tracker (backlog + execution + implementation logs) and docs surface (design docs / knowledge management). Chosen once during workflow setup; the machine-read copy lives in documentation/workflow-config.md (keep the two in sync).

• Selected: [YYYY-MM-DD] by [name]
• Why this pair: [one line — e.g. "team lives in Azure DevOps Boards + Wiki" / "fully offline, no SaaS dependency"]
• Config: documentation/workflow-config.md (ids, process, prefixes)

Frontend / UI Tooling (if applicable)

[Delete if not relevant.]

• UI framework: [React, Vue, Svelte]
• State management: [Redux, Zustand, signals]
• Component library: [internal, vendor]
• Visualisation: [Recharts, D3, ECharts]
• Build / bundler: [Vite, Webpack]
• Live reload / dev experience: [HMR, etc.]

Deployment & Distribution (if applicable)

• Target platform: [cloud, on-prem, desktop, embedded]
• Distribution: [SaaS, downloadable, package registry, app store]
• Installation requirements: [system prerequisites]
• Update mechanism: [how users receive updates]
• Environments: [dev, staging, prod — and any specifics on each]

Technical Requirements & Constraints

Performance

[Concrete targets, not aspirations.]

• [e.g. p95 API latency < 200ms]
• [e.g. ingest pipeline must process N records/sec]

Compatibility

• Operating systems: [supported targets]
• Browsers (if applicable): [supported versions]
• Standards compliance: [protocols, file formats]

Security & Compliance

• Security requirements: [authn, authz, encryption at rest / in transit]
• Compliance standards: [GDPR, HIPAA, SOC2 — as applicable]
• Threat model summary: [key adversaries and trust boundaries]

Scalability & Reliability

• Expected load: [users, requests, data volume, growth projections]
• Availability target: [SLO uptime]
• Disaster recovery: [RPO, RTO]

Technical Decisions & Rationale

Known Limitations

[Tech debt and acknowledged gaps. Each entry should say what it costs us today and when we'd consider addressing it.]

• [Limitation]: [impact today, conditions under which we'd revisit]