ait-crafting

Files (1)

• SKILL.md

SKILL.md (first lines)

# Crafting ait issues

The goal: a fresh agent with no prior context could read the epic + issue + README and start work immediately. **Consultant-ready.**

## The Layered Context Model

```
Initiative or Epic (vision document)
├── Background: What exists, context
├── The Problem: Why this is needed
├── The Vision: What we're building
├── Who Benefits: Users and how
├── Success Criteria: Concrete outcomes (and what success is NOT)
├── Key Principles: Guiding constraints
├── Technical Approach: High-level architecture
├── Key Documents: Links to README, TECHNICAL_OVERVIEW, etc.
└── Phases: Overview of work breakdown
        ↓
Issues (implementation specs)
├── File paths to create/modify
├── Code snippets (schemas, signatures, return formats)
├── Pattern references ("Follow X.php for structure")
├── Acceptance criteria
└── Prerequisites by name ("Uses Team model from 3tz.2")
```

**The initiative/epic has the "why". Issues have the "what".**

For larger features with multiple epics, use an `initiative` as the top-level vision document and group epics beneath it. For smaller features, an epic is sufficient.

Issues can be terse on context because the initiative/epic covers it. But they must be complete on implementation details.

## Workflow

### 1. Calibrate to the project

- Read README.md, CLAUDE.md, TECHNICAL_OVERVIEW.md (if they exist), and any docs mentioned in the discussion or plan.
- Pick a testing mode (see below). This shapes how you design issues and what acceptance criteria mean.

### 2. Distil and gate (when the source is a conversation)

When working from a live discussion rather than an approved plan document, distil the load-bearing parts before creating anything:

- **Goal** — what we're building and for whom, 1–2 sentences
- **What we decided** — concrete decisions that survived
- **What we rejected (and why)** — so a fresh agent doesn't reach for a ruled-out path
- **Phases** — rough breakdown
- **Sharp edges** — things noticed in conversation that aren't obvious from the code

Present it in chat and ask:

> "Does this capture it? Anything missed, mis-weighted, or that I should drop?"

Iterate until the user is happy. **Do not skip this** — the user is the one who knows which exploratory branches mattered and which were dead ends.

Record the rejected paths and their reasons as an `ant` note and reference it from the epic — that's what `ant` is for. Don't paraphrase them into issue descriptions.

**Skip the gate** when converting an already-approved plan-mode plan: approval happened at plan acceptance, and the plan document is the distillation.

For a long or wandering conversation, offer one extra pass before creating issues: save the distillation to a temp file and run the `plan-reconciler` agent over it against the current session. Written summaries reliably drop 10–15% of what was actually discussed; the reconciler catches coverage gaps (did what we said make it into what we wrote?), while the amnesia check in step 7 catches conveyance gaps (can a stranger act on what we wrote?). Different failure modes — don't treat one as covering the other.

### 3. Check for overlapping issues

- Run `ait list --all` and `ait search` for potentially related issues.
- If the user named a parent initiative/epic, read it with `ait show <id>`; if its description is thin, enhance it before creating children.
- If overlap is found, ask before proceeding.

### 4. Create or enhance the initiative/epic

Include ALL of these sections in the description:

```markdown
# [Feature Name]

## Background
[What exists already. Link to relevant docs. 1-2 paragraphs.]

## The Problem
[Why this is needed. What pain point it solves. Bullet points work well.]

## The Vision
[What we are building. Be specific about the solution.]

## Who Benefits
**[User type 1]**: [How they benefit]
**[User type 2]**: [How they benefit]

## What Success Looks Like
- [Concrete outcome 1]
- [Concrete outcome 2]
- [Concrete outcome 3]

**Success is NOT**: [What we are explicitly not optimising for]

## Key Principles
1. **[Principle]**: [Explanation]
2. **[Principle]**: [Explanation]

## Technical Approach
- [High-level architectural decision 1]
- [High-level architectural decision 2]

## Key Documents
- README.md - [What it contains relevant to this]
- [Other doc] - [What it contains]

## Phases
1. **[Phase name]** (P1): [Brief description]
2. **[Phase name]** (P2): [Brief description]

## For implementing agents
If a spec is silent on something load-bearing, note it on the issue and
ask before proceeding - do not silently pick a reading. A gap you surface
is a finding; a gap you paper over is a defect with your name on it.
```

The "For implementing agents" section ships verbatim in every epic: it makes
the surface-don't-improvise norm travel with the tracker, so a cold agent
picking up an issue next month behaves the same as one you briefed by hand.

From ohnotnow/agentic-stuff, MIT.

More from ohnotnow/agentic-stuff