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

What This Skill Does NOT Do

This lean version intentionally omits:

docs/design/

Quick Reference

docs/issues/115-*/

docs/issues/{num}-auth/

docs/adr/NNN-*.md

docs/adr/NNN-*.md

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

dev-context

dev-explore

dev-reports

dev-inquiry

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