Document Type Selection

This skill helps choose the right Metis document type for different kinds of work.

Quick Decision Guide

Is this work, or is it a decision?

• Decision about architecture/approach → ADR
• Work to be done → Continue below

Is this a detailed specification or design document?

• Yes, describes system/feature requirements or design → Specification
• No → Continue below

Does this define WHY the project exists?

• Yes → Vision

Does this create a fundamental capability increment?

• Yes → Initiative

Is this a discrete, completable piece of work?

• Yes, belongs to an initiative → Task
• Yes, standalone (bug/feature/debt) → Backlog Item

Document Types Reference

Parent phase guidance:

• Initiatives are typically created under a published vision
• Tasks are typically created under an initiative in decompose or active phase
• reassign_parent enforces initiative phase (must be decompose/active)

User Terminology Mapping

When users request work items using common terms, map to Metis document types:

When to Create Each Type

Vision

Create when:

• Starting a new project
• Redefining project direction
• Current vision no longer represents objectives

Not a vision: "Build feature X" (initiative), "Fix bugs" (operational), "Q1 goals" (initiatives)

Initiative

Create when:

• Work delivers meaningful capability increment
• Multiple tasks needed
• Discovery/design phases valuable
• Track as distinct project

Not an initiative: Single task, ongoing operations (backlog), aspiration without commitment (keep in backlog)

Task

Create when:

• Clear parent initiative exists
• Discrete, completable unit
• One person can own it
• Done criteria are clear

Not a task: Work with no parent (backlog item), work too large (break down or make initiative)

Backlog Item

Create when:

• Bug discovered in production
• Feature request not tied to initiative
• Tech debt to address when capacity allows
• Operational/maintenance work

Categories: bug, feature, tech-debt

Moving backlog items: Use reassign_parent to move a backlog item into an initiative, or move a task back to backlog.

Specification

Create when:

• Documenting system architecture or feature requirements
• Writing a detailed design document for a project area
• Creating living documentation that evolves as the system changes
• Need a persistent reference for how something works or should work

Not a specification: Architectural decisions (ADR), project planning (initiative), individual work items (task)

Phases: discovery → drafting → review → published (published content remains editable as a living document)

ADR

Create when:

• Making significant architectural decision
• Choosing between meaningful alternatives
• Decision affects multiple initiatives
• Future developers will wonder "why?"

Not an ADR: Trivial decisions, work to be done (task/initiative), meeting notes

Common Mistakes

Edge Cases

Task vs Initiative: Does it need discovery/design phases? If yes, initiative.

Initiative vs Backlog: Committing to it now? If no, backlog.

Backlog vs Task: Does it have a parent? If no, backlog.

Specification vs ADR: Specs describe how something works; ADRs record why a decision was made. A spec may reference ADRs for the reasoning behind design choices.

Cross-cutting work: Create initiative under most relevant parent; tasks can reference other initiatives.

Additional Resources

For detailed decision trees and edge cases:

• references/decision-trees.md - Complete decision framework
• references/when-to-adr.md - ADR-specific guidance