Dev Context (Lean)

Set up working context for GitHub issues. Create formal ADRs when needed.

Two Modes

Mode 1: Issue Working Space (Default)

Trigger: "Set up context for issue #115", "Create working space for feature X"

Creates:

docs/issues/{num}-{short-name}/
├── README.md   # Status, GH link, quick reference
├── plan.md     # Implementation approach
└── notes.md    # Working notes (starts empty)

Process:

1. Create folder docs/issues/{num}-{short-name}/
2. Generate README.md with issue link and status
3. Generate plan.md with implementation approach
4. Create empty notes.md for working notes
5. Return file paths

README.md template:

# Issue #{num}: {Title}

**GitHub**: {link}
**Status**: In Progress
**Created**: {date}

## Overview
{Brief description from issue}

## Related
- Plan: [plan.md](./plan.md)
- Notes: [notes.md](./notes.md)

plan.md template:

# Implementation Plan: {Title}

## Approach
{High-level approach}

## Tasks
- [ ] {Task 1}
- [ ] {Task 2}
- [ ] {Task 3}

## Files to Modify
- {file 1}
- {file 2}

## Notes
{Implementation notes as work progresses}

Mode 2: Architecture Decision Record (ADR)

Trigger: "Create ADR for choosing X over Y", "Document the decision about Z"

Creates:

docs/adr/{NNN}-{decision-name}.md

Process:

1. Find next ADR number (glob docs/adr/*.md, or start at 001)
2. Create docs/adr/ directory if needed
3. Generate ADR from template in references/templates/adr.md
4. Return file path

When to use ADRs:

• Major architectural decisions (database choice, framework selection)
• Decisions that will be questioned later ("why did we do it this way?")
• Decisions with significant tradeoffs worth documenting
• NOT for routine implementation choices

Note: Most decisions don't need formal ADRs. They get captured in devlogs and synthesized into docs/moc/decisions.md during periodic maintenance. Use ADRs sparingly for decisions that truly warrant formal documentation.

What This Skill Does NOT Do

This lean version intentionally omits:

Quick Reference

Lifecycle

Issue Working Space

1. Create when starting multi-session work
2. Update plan.md and notes.md as you work
3. Extract patterns to ai_docs/ if reusable
4. Delete folder when issue closes

ADRs

1. Create for major decisions
2. Never edit once accepted (write new ADR if decision changes)
3. Reference from docs/moc/decisions.md for discoverability

Part of the dev-* Family

See Also

• docs/issues/README.md - Working space conventions
• ai_docs/maintenance-workflows.md - When to extract patterns
• docs/moc/decisions.md - Synthesized decision history