info-project-artifacts

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

What are [Project Artifact] Types?

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. Research can lead to or adjust creation of Spec and/or Decision. Created ad-hoc when questions need investigation; linked to relevant 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 smaller, 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).

[Project Artifact] Require a ProjectId [CRITICAL]

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

We use this [ProjectId] before interacting with any [Project 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 [Project Artifact]?

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

This skill has access to templates for each artifact type.

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

Artifact Storage Structure (Johnny Decimal System)

Naming Convention

All artifacts follow the Johnny Decimal naming system for consistent organization and human readability:

{epicid}.{typecode}.{incrementid}-{typename}-{title}.md

Components:

{epicid} - Epic identifier (0001, 0002, 0003, ...) - zero-padded
- Identifies which epic the artifact belongs to
- ALL artifacts except Retrospective must have an epic
{typecode} - Artifact type code (fixed)
- 1 = Spec
- 2 = Research
- 3 = Decision
- 4 = Story
- 5 = Task
- 9 = Retrospective (project-level only, epic id is 0000)
{incrementid} - Increment counter (0001, 0002, 0003, ...) - zero-padded
- Increments per epic+type combination
- Spec: Always 0001 per epic (one spec per epic)
- Research: 0001, 0002, 0003... per epic
- Decision: 0001, 0002, 0003... per epic
- Story: 0001, 0002, 0003... per epic
- Task: 0001, 0002, 0003... per epic
{typename} - Human-readable type (spec, research, decision, story, task, retrospective)
{title} - Human-readable title in kebab-case (e.g., user-authentication-requirements)

Examples

Artifact	Filename	Meaning
Epic 1 Spec	`0001.1.0001-spec-user-auth-requirements.md`	Epic 1, Spec, 1st (only)
Epic 1 Research	`0001.2.0001-research-oauth-alternatives.md`	Epic 1, Research, 1st
Epic 1 Research	`0001.2.0002-research-jwt-best-practices.md`	Epic 1, Research, 2nd
Epic 1 Decision	`0001.3.0001-decision-jwt-vs-session.md`	Epic 1, Decision, 1st
Epic 1 Story	`0001.4.0001-story-user-login-flow.md`	Epic 1, Story, 1st
Epic 1 Task	`0001.5.0001-task-database-schema-design.md`	Epic 1, Task, 1st
Epic 2 Spec	`0002.1.0001-spec-api-security.md`	Epic 2, Spec, 1st (only)
Retrospective	`0000.9.0001-retrospective-project-closeout.md`	Project-level, Retrospective

Folder Structure

Projects follow a hierarchy that groups artifacts by epic and type:

{ProjectId}/
│
├── {epicid}-{epic-name}/                    # Epic folder (groups related artifacts)
│   ├── {epicid}.1.0001-spec-{title}.md      # Spec file (only one per epic)
│   ├── {epicid}.2.0001-research-{title}.md  # Research files (multiple)
│   ├── {epicid}.2.0002-research-{title}.md
│   ├── {epicid}.3.0001-decision-{title}.md  # Decision files (multiple)
│   ├── {epicid}.3.0002-decision-{title}.md
│   ├── {epicid}.4.0001-story-{title}.md     # Story files (multiple)
│   └── {epicid}.4.0002-story-{title}.md
│
├── {epicid}.5.0001-task-{title}.md          # Task files at project level
├── {epicid}.5.0002-task-{title}.md
├── {epicid}.5.0003-task-{title}.md
│
└── 0000.9.0001-retrospective-{title}.md     # Project-level retrospective

Why this structure:

✅ Visual hierarchy by path: Human immediately sees which epic, which type, which order
✅ Type visible in filename: No ambiguity - 0001.3.0001 is clearly a decision
✅ Johnny Decimal standard: Familiar numbering system, naturally sorts in order
✅ Epic folders group work: All specs, research, decisions, stories for an epic in one folder
✅ Tasks at project level: Not nested, but epic/story IDs in filename show relationships
✅ Human readable: Title at end explains purpose at a glance
✅ Operational oversight: Manager opens folder, immediately sees all work organized

Real Example: User Authentication System

user-auth-system/
│
├── 0001-user-authentication/
│   ├── 0001.1.0001-spec-user-authentication-requirements.md
│   ├── 0001.2.0001-research-oauth-alternatives.md
│   ├── 0001.2.0002-research-jwt-best-practices.md
│   ├── 0001.3.0001-decision-jwt-vs-session.md
│   ├── 0001.3.0002-decision-password-hashing-algorithm.md
│   ├── 0001.4.0001-story-user-login-flow.md
│   ├── 0001.4.0002-story-user-password-reset.md
│   ├── 0001.4.0003-story-account-recovery.md
│   ├── 0001.5.0001-task-design-database-schema.md
│   ├── 0001.5.0002-task-implement-jwt-middleware.md
│   ├── 0001.5.0003-task-create-login-api-endpoint.md
│   ├── 0001.5.0004-task-create-password-reset-endpoint.md
│   ├── 0001.5.0005-task-implement-frontend-auth-integration.md
│   └── 0001.5.0006-task-add-session-timeout-logic.md
│
├── 0002-api-rate-limiting/
│   ├── 0002.1.0001-spec-api-rate-limiting-requirements.md
│   ├── 0002.2.0001-research-rate-limiting-strategies.md
│   ├── 0002.3.0001-decision-token-bucket-vs-sliding-window.md
│   ├── 0002.4.0001-story-implement-rate-limiting.md
│   ├── 0002.4.0002-story-add-rate-limit-headers.md
│   ├── 0002.5.0001-task-implement-rate-limiter-middleware.md
│   ├── 0002.5.0002-task-add-redis-caching.md
│   └── 0002.5.0003-task-monitoring-rate-limit-metrics.md
│
└── 0000.9.0001-retrospective-project-closeout.md

⚠️ FAILURE MODE: Notice that ALL tasks (0001.5., 0002.5.) are stored INSIDE their epic folders, NOT at the project level. Tasks at the project root level with no epic folder are an ERROR - they indicate orphaned work with unclear ownership and dependencies.

Important Constraint: All Artifacts Belong to an Epic

Every artifact MUST be associated with an epic (except Retrospective):

✅ Spec: Always 1 per epic (0001.1.0001, 0002.1.0001, etc.)
✅ Research: Multiple per epic (0001.2.0001, 0001.2.0002, etc.)
✅ Decision: Multiple per epic (0001.3.0001, 0001.3.0002, etc.)
✅ Story: Multiple per epic (0001.4.0001, 0001.4.0002, etc.)
✅ Task: Multiple per epic (0001.5.0001, 0001.5.0002, etc.)
✅ Retrospective: Project-level, not tied to specific epic (0000.9.0001)

This ensures no orphaned artifacts and clear lineage from epic down to task.

Obsidian Linking

All artifacts use Obsidian wiki-style linking for navigation and relationship management:

[[{epicid}-{epic-name}]] # Link to epic folder
[[{epicid}.{typecode}.{incrementid}-{typename}-{title}]] # Link to artifact

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

Examples:

[[0001-user-authentication]] - Links to Epic 1 folder
[[0001.1.0001-spec-user-authentication-requirements]] - Links to specific spec
[[0001.5.0001-task-design-database-schema]] - Links to specific task

Frontmatter Links: All artifact templates use target: field (not itemId:) to specify link targets that match filenames. When creating artifacts, replace placeholder filenames with actual titles following the naming convention.

Example frontmatter:

links:
  - type: epic
    target: 0001-user-authentication
  - type: spec
    target: 0001.1.0001-spec-user-auth-requirements
  - type: task
    target: 0001.5.0001-task-schema-design

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

Effort Estimation 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 (Epic, Spec, Story, Task, Decision, Research, Retrospective).

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 task relationship schema, artifact content structure, and link type definitions for all artifact types (Epic, Spec, Story, Task).

Install Skill

SKILL.md