artifacts-creating-and-managing

What this skill does

# Artifacts: Creating and Managing

## Table of Contents

1. [Quick Start](#quick-start)
2. [Triggers](#triggers)
3. [Purpose](#purpose)
4. [When to Use Artifacts](#when-to-use-artifacts)
5. [Directory Structure](#directory-structure)
6. [File Naming Conventions](#file-naming-conventions)
7. [Core Rules](#core-rules)
8. [Category Definitions](#category-definitions)
9. [Helper Scripts](#helper-scripts)
10. [Integration Pattern](#integration-pattern)
11. [Supporting Files](#supporting-files)
12. [Best Practices](#best-practices)
13. [Red Flags to Avoid](#red-flags-to-avoid)

## Quick Start

See [scripts/create_adr.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_adr.py) for creating ADRs.

See [scripts/create_research_topic.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_research_topic.py) for creating research topics.

See [scripts/create_implementation_plan.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_implementation_plan.py) for creating implementation plans.

## Triggers

Trigger with phrases like:
- "create an ADR"
- "create ADR for [decision]"
- "research [topic]"
- "create research topic"
- "spike investigation on [topic]"
- "create spike for [investigation]"
- "implementation plan for [feature]"
- "create analysis"
- "analyze [subject]"
- "document decision"
- "plan implementation"

## Purpose

Standardizes how artifacts are created and organized within `.claude/artifacts/` directory. Artifacts are temporary work products that support development but don't belong in version control or permanent documentation.

## When to Use This Skill

Use when asked to:
- Document architectural decisions ("create an ADR for event sourcing")
- Research technical topics ("research GraphQL libraries for React")
- Plan feature implementations ("create implementation plan for 2FA")
- Conduct time-boxed investigations ("spike on OAuth2 integration")
- Analyze existing code or architecture ("analyze performance bottlenecks")

Do NOT use when:
- Creating permanent documentation (use `docs/` directory instead)
- Writing source code (use `src/` directory)
- User needs quick inline answers (respond directly in conversation)

## When to Use Artifacts

**Use artifacts when:**
- Conducting research ("research GraphQL libraries")
- Creating spikes ("spike on authentication approaches")
- Writing analysis ("analyze performance bottlenecks")
- Documenting decisions (ADRs)
- Planning implementations
- Capturing session notes
- Recording investigation results

**Don't use artifacts for:**
- Permanent documentation (use `docs/` instead)
- Source code (use `src/` instead)
- Tests (use `tests/` instead)
- Configuration (use config files)

## Directory Structure

```
.claude/artifacts/
├── YYYY-MM-DD/                    # Date-based organization
│   ├── research/                  # Research topics
│   │   └── topic-name.md
│   ├── spikes/                    # Technical spikes
│   │   └── spike-name.md
│   ├── analysis/                  # Code/architecture analysis
│   │   └── analysis-name.md
│   ├── plans/                     # Implementation plans
│   │   └── plan-name.md
│   ├── sessions/                  # Session notes
│   │   └── session-name.md
│   └── adr/                       # Architecture Decision Records
│       └── NNN-decision-name.md
└── completed/                     # Archived artifacts
    └── adr/
        └── NNN-decision-name.md
```

## File Naming Conventions

**Research topics:**
```
.claude/artifacts/YYYY-MM-DD/research/topic-name.md
Example: .claude/artifacts/2025-12-24/research/graphql-libraries.md
```

**Spikes:**
```
.claude/artifacts/YYYY-MM-DD/spikes/spike-name.md
Example: .claude/artifacts/2025-12-24/spikes/oauth2-integration.md
```

**Analysis:**
```
.claude/artifacts/YYYY-MM-DD/analysis/analysis-name.md
Example: .claude/artifacts/2025-12-24/analysis/performance-bottlenecks.md
```

**Implementation plans:**
```
.claude/artifacts/YYYY-MM-DD/plans/feature-name-plan.md
Example: .claude/artifacts/2025-12-24/plans/user-authentication-plan.md
```

**ADRs:**
```
.claude/artifacts/YYYY-MM-DD/adr/NNN-decision-title.md
Example: .claude/artifacts/2025-12-24/adr/001-use-event-sourcing.md
```

## Core Rules

1. **Date-based organization** - All artifacts under `YYYY-MM-DD/` directory
2. **Kebab-case names** - Use hyphens, lowercase, no spaces
3. **Category folders** - research/, spikes/, analysis/, plans/, adr/
4. **Markdown format** - All artifacts are .md files
5. **Templated creation** - Use helper scripts for consistency
6. **Completion tracking** - Move to `completed/` when done

## Category Definitions

### Research
**Purpose:** Investigate libraries, tools, or approaches

**Template:** See [templates/research_template.md](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/templates/research_template.md)

**Example usage:** "Research GraphQL client libraries for React"

### Spikes
**Purpose:** Time-boxed technical investigation

**Template:** Spike template not yet created (use research template as starting point)

**Example usage:** "Spike on OAuth2 integration with existing auth system"

### Analysis
**Purpose:** Investigate existing code/architecture

**Template:** Analysis template not yet created (use research template as starting point)

**Example usage:** "Analyze performance bottlenecks in API handlers"

### Plans
**Purpose:** Document implementation approach

**Template:** See [templates/implementation_plan_template.md](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/templates/implementation_plan_template.md)

**Example usage:** "Plan implementation of two-factor authentication"

### ADRs (Architecture Decision Records)
**Purpose:** Document architectural decisions

**Template:** See [templates/adr_template.md](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/templates/adr_template.md)

**Example usage:** "ADR 001: Use Event Sourcing for Audit Trail"

## Helper Scripts

All scripts located in `.claude/skills/artifacts-creating-and-managing/scripts/`:

### create_adr.py

See [scripts/create_adr.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_adr.py) for full script.

**Required:** --title, --status, --context
**Optional:** --decision, --consequences

### create_research_topic.py

See [scripts/create_research_topic.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_research_topic.py) for full script.

**Required:** --topic, --objective
**Optional:** --questions (multiple)

### create_spike.py

Note: Spike script not yet created. Use create_research_topic.py as alternative.

### create_analysis.py

Note: Analysis script not yet created. Use create_research_topic.py as alternative.

### create_implementation_plan.py

See [scripts/create_implementation_plan.py](/Users/dawiddutoit/projects/claude/custom-claude/skills/artifacts-creating-and-managing/scripts/create_implementation_plan.py) for full script.

**Required:** --feature, --overview
**Optional:** --steps (multiple), --risks

## Integration Pattern

**Typical workflow:**

1. **Create artifact:** Use helper scripts (see Helper Scripts section)
2. **Work on artifact:**
   - Add findings, analysis, or decisions
   - Reference code, documentation, or other artifacts
   - Update as investigation progresses
3. **Complete artifact:**
   - Mark as complete (status: accepted/completed)
   - Move to `completed/` if ADR
   - Reference in code or documentation
   - Archive or delete if temporary
4. **Cross-reference:**
   - Link from code comments: `// See: .claude/artifacts/YYYY-MM-DD/research/topic.md`
   - Link from documentation: `docs/` references artifacts
   - Link between artifacts: Related ADRs re