info-planning-artifacts

name	info-planning-artifacts
description	Use to know about Planning Artifacts used in project management.

What are [Planning Artifact] Types?

• PRD: Product Requirements Document, A high-level statement of what the product should achieve. They capture the needs and expectations of stakeholders. A PRD informs managers in the creation of one or more Epic.
• Epic: A large body of work that is described by Stories. An Epic is always accompanied by a Spec, they have a 1:1 relationship.
• Spec: A detailed description of the project's requirements and objectives. It leads to creation of one or more Story.
• Research: Information gathering and analysis conducted to inform project decisions. Primary phase: Planning/Initiation (during PRD/Epic/Spec creation). Secondary phase: ad-hoc during Execution when implementation raises unknowns. Research informs Spec, Decision, and project direction. Linked to PRD, Epic, Spec, Decision, Story, or Task.
• Decision: A conclusion reached after evaluating options, often based on Research. Decision can influence Spec and project direction. Created during Initiation/Planning (for strategic decisions) or during Execution (for implementation decisions). Status must be "Decided" or "Unresolved". All Decision artifacts with status "Unresolved" MUST be linked to the Retrospective during the Closing phase.
• Story: A scenario or use case, manageable piece of work derived from an Epic. Story always contain "user stories". Story are always implemented by Task.
• Task: A specific piece of work that needs to be completed as part of a Story. They are always linked to both a Story and an Epic. They can also be linked to other Task in interesting ways (e.g., blocking, dependent on, related to).
• Retrospective: A reflective artifact created at the end of an epic or project phase to capture lessons learned, successes, and areas for improvement. It summarizes insights from the team and stakeholders to inform future projects. Each Retrospective is linked to its corresponding Epic and any unresolved Decision artifacts.

[Planning Artifact] Require a ProjectId [CRITICAL]

Every [Planning Artifact] must be associated with a [ProjectId] to ensure proper organization and retrieval.

We use this [ProjectId] before interacting with any [Planning Artifact]. (Or if required, on every interaction)

ProjectId Naming and Format

ProjectId Convention:

• Format: slugified-project-name (kebab-case, lowercase alphanumeric + hyphens)
• Source: Derived from git repository name or project name
• Generated by: ./scripts/get_project_id.sh (automatically slugifies)
• Examples:
  • Repository: github.com/username/dotfiles → ProjectId: dotfiles
  • Project name: "User Authentication System" → ProjectId: user-authentication-system
  • Example name "My App v2" → ProjectId: my-app-v2

How do we write [Planning Artifact]?

[!NOTE] Wether creating a new [Planning Artifact] or updating an existing one, consistency is key.

This skill has access to templates for each artifact type.

When creating or updating [Planning Artifact], use the corresponding template to ensure consistency.

Artifact Storage Structure (Johnny Decimal System)

Projects organize all artifacts using type-based Johnny Decimal structure, grouping by artifact category rather than by epic:

1-prds/                                    # PRD layer (strategic)
  1.1.1-prd-dayz-modding-template.md
  1.2.1-prd-user-authentication.md
2-epics/                                   # Epic layer (major work)
  2.1.1-epic-separate-cli-tool.md
  2.2.1-epic-user-auth-system.md
3-research/                                # Research layer (investigation)
  3.1.1-research-oauth-alternatives.md
  3.2.1-research-jwt-best-practices.md
  3.3.1-research-cli-modding-patterns.md
4-stories/                                 # Story layer (user scenarios)
  4.1.1-story-user-login-flow.md
  4.2.1-story-password-reset.md
  4.3.1-story-template-extraction.md
5-tasks/                                   # Task layer (implementation)
  5.1.1-task-database-schema-design.md
  5.2.1-task-api-endpoints.md
  5.3.1-task-extract-template-files.md
9-retrospectives/                          # Retrospective layer (closure)
  9.1.1-retrospective-epic-1-closeout.md
  9.2.1-retrospective-epic-2-closeout.md

Naming Convention

All artifacts follow Johnny Decimal format with this pattern:

{category}.{sequence}.{increment}-{type}-{title}.md

Where:

• {category} - Top-level artifact category (1-9)

  • 1 = PRD (Product Requirements)
  • 2 = Epic (Major work packages) and Spec (Detailed requirements, paired 1:1 with Epic)
  • 3 = Research (Investigation and analysis)
  • 4 = Story (User scenarios)
  • 5 = Task (Implementation work)
  • 6 = Decision (Choices and conclusions)
  • 9 = Retrospective (Closure and reflection)

• {sequence} - Sequential counter per category (1, 2, 3, ...)

  • Increments each time you create a new artifact in that category
  • Example: First PRD is 1.1.1, second is 1.2.1, third is 1.3.1

• {increment} - Always 1 for single artifacts (reserved for variants/versions)

• {type} - Human-readable artifact type (prd, epic, spec, research, story, task, decision, retrospective)

• {title} - Human-readable title in kebab-case (e.g., user-authentication-system)

Relationship: Artifacts Link Across Categories

Artifacts maintain relationships through frontmatter links. The typical flow is:

PRD → Epic: A PRD informs which Epics to create

• PRD 1.1.1-prd-user-auth.md links to Epic 2.2.1-epic-user-auth-system.md
• Research often happens here to validate strategic direction

Epic → Research: Epic planning may require investigation

• Epic 2.1.1-epic-separate-cli.md links to Research 3.3.1-research-cli-modding-patterns.md
• Research informs Epic scope and approach during Planning phase

Epic → Stories: An Epic is broken down into Stories

• Epic 2.1.1-epic-separate-cli.md links to Story 4.3.1-story-template-extraction.md

Story → Tasks: A Story is implemented via Tasks

• Story 4.3.1-story-template-extraction.md links to Task 5.3.1-task-extract-template-files.md

Ad-hoc Research: Unexpected questions during execution

• Task 5.1.1-task-database-schema-design.md links to Research 3.1.1-research-performance-benchmarks.md
• Research happens ad-hoc when implementation reveals unknowns (secondary, not primary)

Examples

Artifact	Filename	Meaning
PRD 1	1-prds/1.1.1-prd-dayz-modding-template.md	Strategic direction: Separate DayZ template
PRD 2	1-prds/1.2.1-prd-user-authentication.md	Strategic direction: Auth system
Epic 1	2-epics/2.1.1-epic-separate-cli-tool.md	Major work: Extract template from CLI
Spec 1	2-epics/2.1.1-spec-separate-cli-requirements.md	Requirements: CLI template extraction
Epic 2	2-epics/2.2.1-epic-user-auth-system.md	Major work: Build authentication
Spec 2	2-epics/2.2.1-spec-user-auth-requirements.md	Requirements: User authentication system
Research 1	3-research/3.2.1-research-jwt-best-practices.md	Investigation: JWT vs Sessions
Research 2	3-research/3.3.1-research-oauth-alternatives.md	Investigation: OAuth options
Story 1	4-stories/4.1.1-story-user-login-flow.md	User scenario: Login process
Story 2	4-stories/4.3.1-story-template-extraction.md	User scenario: Extract template
Task 1	5-tasks/5.1.1-task-database-schema-design.md	Implementation: Design schema
Task 2	5-tasks/5.3.1-task-extract-template-files.md	Implementation: Extract files
Retrospective	9-retrospectives/9.1.1-retrospective-epic-1-closeout.md	Closure: Epic 1 lessons learned

Why This Structure

• ✅ True Johnny Decimal: First digit denotes category, enabling visual scan at top level
• ✅ Type discovery: All PRDs together, all Epics together—easier to browse and maintain
• ✅ Flat organization: No nested folders per epic—scales well with many artifacts
• ✅ Clear relationships: Frontmatter links establish parent-child relationships across categories
• ✅ Chronological order: Artifacts naturally sort by creation order within category
• ✅ Flexible decomposition: One PRD can link to multiple Epics; Epics can link to multiple Stories/Tasks
• ✅ Query-friendly: "Show me all Stories for Epic 2" is clear (look at Story frontmatter)
• ✅ Research lifecycle: Research happens primarily during Planning (PRD/Epic phase); ad-hoc Research surfaces during Execution as needed

Artifact Relationships Through Frontmatter

Rather than folder nesting, relationships are defined in artifact frontmatter:

Each artifact maintains parent/child links:

# In Epic 2.1.1
links:
  - type: prd
    target: 1.1.1-prd-dayz-modding-template
  - type: story
    target: 4.3.1-story-template-extraction

# In Story 4.3.1
links:
  - type: epic
    target: 2.1.1-epic-separate-cli-tool
  - type: task
    target: 5.3.1-task-extract-template-files
  - type: research
    target: 3.3.1-research-cli-modding-patterns

# In Task 5.3.1
links:
  - type: story
    target: 4.3.1-story-template-extraction
  - type: epic
    target: 2.1.1-epic-separate-cli-tool

This creates a web of relationships without directory nesting.

Obsidian Linking

All artifacts use Obsidian wiki-style linking for navigation across the flat artifact structure:

Linking format: [[{category}.{sequence}.{increment}-{type}-{title}]]

This works across all categories, creating a hyperlinked web of relationships.

Examples:

• [[1.1.1-prd-dayz-modding-template]] - Links to PRD 1
• [[2.1.1-epic-separate-cli-tool]] - Links to Epic 1
• [[3.2.1-research-jwt-best-practices]] - Links to Research artifact
• [[4.3.1-story-template-extraction]] - Links to Story artifact
• [[5.3.1-task-extract-template-files]] - Links to Task artifact

Important: Link targets MUST match the actual filename exactly (without .md extension).

Frontmatter Links: All artifact templates use target: field to specify link targets. The type: field identifies the artifact category:

links:
  - type: prd
    target: 1.1.1-prd-dayz-modding-template
  - type: epic
    target: 2.1.1-epic-separate-cli-tool
  - type: research
    target: 3.2.1-research-jwt-best-practices
  - type: story
    target: 4.3.1-story-template-extraction
  - type: task
    target: 5.3.1-task-extract-template-files

See individual artifact templates for detailed linking examples in frontmatter and body.

Effort Estimation Hierarchy

PRD and Spec are not estimated directly. Instead, estimation flows down the hierarchy.

Epic, Story, and Task have different estimation levels:

Epic Estimation

• Estimated in weeks or months (high-level)
• Derived from Story points of child Story (sum all stories)
• Used for: Timeline planning, resource allocation
• Refinement: As Story are created and estimated

Story Estimation

• Estimated in story points (3-13 points typical range)
• Based on: Complexity, risk, dependencies
• Used for: Release planning, sprint capacity
• Refinement: During Planning phase before creating Task

Task Estimation

• Estimated in story points (1-8 points)
• Based on: Specific implementation work, clear acceptance criteria
• Constraint: If Task > 8 points, it should be split into smaller Task
• Used for: Day-to-day execution, capacity planning, identifying blockers
• Refinement: Continuous during Execution as understanding grows

Why this hierarchy matters:

• Epic scale helps executives understand project timeline
• Story scale helps team understand sprint commitment
• Task scale helps individual contributors understand daily work
• Misalignment = surprises (story was "5 points" but contained "3x13 point tasks")

How are Task relationships described?

Task can be linked to other Task in interesting ways. Choose the relationship type that best describes the interaction:

Task Relationship Types

When to use "blocking":

• THIS Task must finish BEFORE other Task can start
• Use: Document dependencies for critical path analysis
• Example: "Database schema design blocks API implementation"
• From Task perspective: "This task blocks: api-task-001"

When to use "dependent_on":

• THIS Task cannot start UNTIL another Task finishes
• Use: Identify what's blocking your progress
• Example: "API implementation depends on database schema design"
• From Task perspective: "This task is dependent_on: database-task-001"
• Note: "blocking" and "dependent_on" are the same relationship viewed from opposite directions

When to use "related_to":

• THIS Task is connected but does NOT have direct dependency
• Use: Track work in same area (e.g., similar components, same feature)
• Example: "Frontend auth task is related to backend auth task" (parallel, not blocking)
• Use sparingly - don't link everything

When to use "duplicate_of":

• THIS Task is a duplicate of another Task
• Use: When duplicate work is discovered, mark the duplicate and consolidate
• Example: "This task is duplicate_of: auth-task-002"
• Action: Cancel this task, redirect work to the original

Linking to Research or Decision:

• "influenced_by_research": This task was shaped by investigation/analysis
• "influenced_by_decision": This task was created based on a decision made
• Use: For traceability and understanding "why was this built this way?"

Parent artifact links (MANDATORY):

• Every Task MUST link to: parent Story AND parent Epic
• This establishes the hierarchy and enables queries like "all tasks in this epic"

Artifact Status Transitions

Each artifact type has valid status progressions that guide state management throughout the project lifecycle.

→ See: references/status-flow.md for detailed status flow diagrams and descriptions for all artifact types (PRD, Epic, Research, Story, Task, Retrospective, Decision).

Artifact Schemas and Content Structure

All artifacts follow consistent schema patterns for organization and linking. Each artifact type has specific frontmatter requirements and content sections.

→ See: references/schema.md for detailed schema definitions, artifact content structure, and link type definitions for all artifact types (PRD, Epic, Research, Story, Task, Retrospective, Decision).