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:

Create folder docs/issues/{num}-{short-name}/
Generate README.md with issue link and status
Generate plan.md with implementation approach
Create empty notes.md for working notes
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:

Find next ADR number (glob docs/adr/*.md, or start at 001)
Create docs/adr/ directory if needed
Generate ADR from template in references/templates/adr.md
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:

| Old Feature | Why Removed | Alternative | |-------------|-------------|-------------| | PRD generation | GitHub issue IS the PRD | Write clear issues | | Design docs per feature | Only major systems need design docs | docs/design/ for systems | | Spec docs | Plan IS the spec | Use plan.md | | Cross-reference ceremony | Overkill for most work | Keep it simple |

Quick Reference

| Request | Mode | Output | |---------|------|--------| | "Set up context for issue #115" | Issue | docs/issues/115-*/ | | "Create working space for auth" | Issue | docs/issues/{num}-auth/ | | "Create ADR for X vs Y decision" | ADR | docs/adr/NNN-*.md | | "Document decision about caching" | ADR | docs/adr/NNN-*.md |

Lifecycle

Issue Working Space

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

ADRs

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

Part of the dev-* Family

| Skill | Purpose | |-------|---------| | dev-context | Set up working space, create ADRs | | dev-explore | Generate/update MOC documentation | | dev-reports | Write devlogs and status reports | | dev-inquiry | Technical investigation and spikes |