Proposal: type conventions and body sections for organizational / PM knowledge

[nyechiel]

Summary

OKF's existing sample bundles and conventional headings (# Schema, # Examples, # Citations) are oriented toward data catalogs - tables, datasets, metrics. But the spec itself is explicitly domain-agnostic, and the format works naturally for organizational and product management knowledge: decision records, stakeholder maps, initiative tracking, and operational playbooks. This issue proposes lightweight conventions that would help producers and consumers in this space converge on common patterns.

Motivation

I run an AI-augmented PM workspace where agents consume structured knowledge to prepare meeting briefs, triage backlogs, and draft product specs. The knowledge base is a directory of markdown files with YAML frontmatter, cross-linked by standard markdown links - essentially an OKF bundle that predates the spec. The pattern works well, but every team building something similar reinvents the same concept types and body sections from scratch.

The data-analytics conventions (table schemas, column descriptions, join paths) solve a real problem for that domain. Organizational knowledge has an equivalent set of recurring structures that would benefit from the same lightweight standardization:

1. Decision records need alternatives considered, rationale, and status - not schemas
2. Stakeholder concepts need roles, responsibilities, and relationship links - not column types
3. Initiatives and epics need acceptance criteria, dependencies, and progress - not SQL examples
4. Playbooks need steps, triggers, and escalation paths - not data lineage

These are common enough across PM, engineering management, and operations teams that shared conventions would reduce friction for both producers (what should I generate?) and consumers (what can I expect to find?).

Proposed type values

Following the spec's approach (types are free-form strings, not a registry), these are suggested conventions:

• Decision - a record of a choice made, with context, alternatives, and rationale
• Initiative - a scoped effort with goals, acceptance criteria, and dependencies (maps to Epics, OKRs, projects)
• Stakeholder - a person or team with roles and relationships to other concepts
• Playbook - a repeatable process with triggers, steps, and escalation paths

Proposed conventional body sections

Analogous to how # Schema, # Examples, and # Citations carry conventional meaning for data concepts:

Heading	Applies to	Purpose
# Stakeholders	Initiative, Decision	People/teams who own, contribute to, or are affected by this concept
# Acceptance Criteria	Initiative	What "done" looks like - measurable conditions
# Dependencies	Initiative	Concepts that block or are blocked by this one
# Alternatives Considered	Decision	Options evaluated and why they were not chosen
# Rationale	Decision	Why this alternative was selected
# Steps	Playbook	Ordered actions to execute the process
# Triggers	Playbook	Conditions that initiate this playbook

Example concept files

Decision record:

---
type: Decision
title: RAG vs. compiled knowledge base
description: Chose compiled knowledge over chunked RAG for product knowledge retrieval.
tags: [architecture, knowledge, retrieval]
timestamp: 2026-05-15T10:00:00Z
---

# Context
Our AI assistant retrieves product knowledge to answer seller questions.
Traditional RAG (chunk + embed + vector search) loses document structure
and cross-references.

# Alternatives Considered
- **Chunked RAG** - lower upfront cost, but retrieval quality degrades
  with complex multi-hop questions
- **Knowledge graph** - highest fidelity, but requires dedicated infra
  and a separate query language

# Rationale
Compiled markdown preserves structure, is human-auditable, and can be
version-controlled alongside the product. Agents can follow cross-links
for multi-hop reasoning without a graph database.

# Stakeholders
- [Engineering Lead](/stakeholders/engineering-lead.md) - implementation owner
- [Data Scientist](/stakeholders/data-scientist.md) - evaluation metrics

# Citations
1. [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)

Stakeholder:

---
type: Stakeholder
title: Platform Engineering
description: Team responsible for infrastructure, CI/CD, and developer tooling.
tags: [engineering, platform, infrastructure]
timestamp: 2026-06-01T09:00:00Z
---

# Responsibilities
- Production infrastructure and deployment pipelines
- Developer tooling and internal platforms
- SLA ownership for core services

# Relationships
- Owns [CI/CD Pipeline](/playbooks/ci-cd-pipeline.md)
- Contributes to [Platform Migration](/initiatives/platform-migration.md)
- Consumed by [Product Team](/stakeholders/product-team.md) for deployment

Relationship to spec

This proposal is fully backward-compatible with OKF v0.1:

• Types are already free-form (SPEC section 4.1) - this suggests conventions, not requirements
• Body sections follow the same pattern as existing conventional headings - producers SHOULD use them, consumers SHOULD handle their absence
• No new required fields - all proposed frontmatter uses existing recommended fields (title, description, tags, timestamp)
• Cross-linking uses standard markdown links per SPEC section 5

The only addition to the spec itself would be expanding the "conventional headings" table in section 4.2 to include the organizational knowledge headings listed above.

Next steps

I'm happy to contribute:

1. A sample bundle demonstrating these conventions (sanitized from a real PM workspace)
2. Documentation for the proposed types and body sections
3. A lightweight producer that generates organizational knowledge bundles from project management tools (Jira, etc.)

Feedback welcome on whether these conventions belong in the spec itself, in a companion "domain guide" document, or simply as a well-documented sample bundle.