07 Knowledge Management Practice

Context

The calab-handbook now uses a 4-level diagram hierarchy (L1–L4) to decompose value streams into detailed process and procedure maps:

• L1 — Value Stream Maps (block-beta columns, owned by VS Owners)
• L2 — Process Maps (horizontal swimlanes = Management Practices, owned by primary Mgmt Practice)
• L3 — Sub-process Maps (decoupled from L2 due to complexity)
• L4 — Procedure Maps (horizontal swimlanes = applications/systems/decision-makers)

This hierarchy, along with the diagram conventions (colour palette, templates, navigation patterns, mcp-mermaid validation workflow), requires a designated Management Practice to own and govern it.

Additionally, the handbook itself is a knowledge management artefact that currently has no governing Management Practice. Content architecture standards, documentation hierarchy enforcement, cross-practice documentation coordination, and template ownership all need a clear home.

The “Knowledge Management Practice” is already referenced in the HR Promotion & Performance Review Policy (in a Mermaid diagram showing functional practice involvement), but was never scaffolded as a formal Management Practice with the standard folder structure.

Decision

Create a Knowledge Management Practice with the following responsibilities:

Scope

1. Diagram hierarchy governance — Own the L1–L4 diagram convention, colour palette, templates, and hierarchical navigation standards
2. Content architecture standards — Define and enforce the folder structure, naming conventions, and content type taxonomy
3. Documentation templates — Own the reusable templates in content/_authoring/diagrams/mermaid/ and coordinate with other practices on practice-specific templates
4. Cross-practice documentation coordination — Ensure MECE coverage across value streams and practices, identify gaps, and facilitate documentation efforts
5. Handbook platform governance — Own the Quartz configuration, theming decisions, and publishing workflow (in coordination with the devops and devweb agents)

Placement

The Knowledge Management Practice should be placed within an appropriate Guild. The recommended options are:

Option	Guild	Rationale
A (Recommended)	GL05 Administration Guild	Knowledge management is an internal operational function alongside HR Management. Administrative practices support the organisation’s infrastructure.
B	GL01 Executive Guild	Knowledge is a strategic asset. Placing it alongside Strategy Mgmt and Financial Mgmt elevates its governance priority.

Folder Structure

Follow the standard Management Practice scaffold (identical to all 16 existing practices):

02 Guilds/<Guild>/Practices/Knowledge Management/
  README.md
  01 Policies/
    .gitkeep
  02 Processes/
    .gitkeep
  03 Procedures/
    .gitkeep
  04 Guides/
    .gitkeep
  05 Templates/
    .gitkeep

Note: Governance artifacts (diagrams, plans, specs) are now centralized in content/_authoring/ rather than per-practice metadata/ directories.

Initial Content

The README.md should document:

• Practice scope (the 5 responsibilities listed above)
• Relationship to the skills/mermaid-diagrams/SKILL.md agent skill
• Cross-references to diagram templates in content/_authoring/diagrams/mermaid/
• Ownership model for the L1–L4 hierarchy
• Review cadence for diagram conventions

Consequences

Positive

• Clear ownership for diagram conventions, templates, and content architecture
• Single point of accountability for handbook quality and consistency
• Resolves the existing dangling reference in the HR policy Mermaid diagram
• Enables governance of the L1–L4 diagram hierarchy as it scales
• Total Management Practices: 16 → 17

Negative

• One additional practice to maintain (minimal overhead given its governance role)
• Requires CODEOWNERS entry (when CODEOWNERS is implemented per Decision 06 scaffolding)

Neutral

• Does not change any existing practice’s scope or ownership
• The skills/mermaid-diagrams/SKILL.md agent skill remains the authoritative technical reference for agents; the Knowledge Management Practice provides the human-facing governance layer

Alternatives Considered

1. Distribute Responsibilities Across Existing Practices

Assign diagram governance to Technology Guild, content architecture to Executive Guild, etc.

• Pros: No new practice to create
• Cons: Fragmented ownership; no single accountable party; coordination overhead increases as the handbook grows
• Why not chosen: The interdependencies between diagram conventions, content architecture, and template governance require unified ownership

2. Create a “Documentation Practice” Instead

A narrower practice focused only on documentation standards.

• Pros: Tighter scope
• Cons: Misses the broader knowledge management mandate (diagram governance, cross-practice coordination, content architecture); naming doesn’t align with the existing Mermaid diagram reference
• Why not chosen: “Knowledge Management” is already referenced in the codebase and is the industry-standard term for this discipline

3. Defer Indefinitely

Continue without a Knowledge Management Practice.

• Pros: No effort required
• Cons: Diagram conventions have no governance; content architecture standards drift; the HR policy diagram reference remains a dangling link
• Why not chosen: The L1–L4 hierarchy requires clear ownership to scale

Related Decisions

• Decision 06: Automated Content Scaffolding (established the folder patterns this practice will follow)
• Value Stream Template (content/_authoring/diagrams/mermaid/value-stream-template.md)
• Mermaid Diagrams Skill (.opencode/skills/mermaid-diagrams/SKILL.md)

---

Date: 2026-02-24 Decided By: [Pending] Approved By: [Pending]