work-intake

What this skill does

# Work Intake

## Overview

Every work request flows through intake. This skill determines scope, gathers requirements, and routes to the appropriate workflow.

**Core principle:** No work is too small to track, no work is too large to decompose.

**Announce at start:** "I'm using work-intake to understand and scope this request before beginning."

## The Intake Flow

```
┌─────────────────────────────────────────────────────────────────────┐
│                        REQUEST RECEIVED                              │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│               STEP 0: PROJECT BOARD READINESS (GATE)                │
│  Is GITHUB_PROJECT_NUM set?                                         │
│  Is project board accessible?                                       │
│  Are required fields configured?                                    │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    CLARIFYING QUESTIONS                              │
│  What is the user trying to achieve?                                │
│  What does success look like?                                        │
│  What constraints exist?                                             │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      SCOPE ASSESSMENT                                │
│  How much investigation is needed?                                   │
│  How many deliverables?                                              │
│  How many unknowns?                                                  │
└─────────────────────────────┬───────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┬───────────────┐
              ▼               ▼               ▼               ▼
         ┌────────┐     ┌──────────┐    ┌──────────┐    ┌──────────┐
         │TRIVIAL │     │  SMALL   │    │  LARGE   │    │ MASSIVE  │
         │        │     │          │    │          │    │          │
         │1 issue │     │1-3 issues│    │1 epic    │    │Initiative│
         │no unkn.│     │few unkn. │    │research  │    │multi-epic│
         └───┬────┘     └────┬─────┘    └────┬─────┘    └────┬─────┘
             │               │               │               │
             ▼               ▼               ▼               ▼
      issue-prerequisite  issue-prerequisite  epic-management  initiative-
      + project-board-    + decomposition    + research spikes  architecture
        enforcement       + project-board-  + project-board-  + project-board-
                           enforcement       enforcement       enforcement
```

## Step 0: Project Board Readiness (GATE)

**Before any work intake, verify project board infrastructure is ready.**

This is a gate. Do not proceed to clarifying questions until this passes.

```bash
# Verify environment variables are set
if [ -z "$GITHUB_PROJECT_NUM" ]; then
  echo "BLOCKED: GITHUB_PROJECT_NUM not set"
  echo "Set with: export GITHUB_PROJECT_NUM=<number>"
  exit 1
fi

if [ -z "$GH_PROJECT_OWNER" ]; then
  echo "BLOCKED: GH_PROJECT_OWNER not set"
  echo "Set with: export GH_PROJECT_OWNER=@me  # or org name"
  exit 1
fi

# Verify project is accessible
if ! gh project view "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json > /dev/null 2>&1; then
  echo "BLOCKED: Cannot access project $GITHUB_PROJECT_NUM"
  echo "Verify project exists and you have access"
  exit 1
fi

# Verify required fields exist
FIELDS=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --format json | jq -r '.fields[].name')

for required in "Status" "Type" "Priority"; do
  if ! echo "$FIELDS" | grep -q "^$required$"; then
    echo "WARNING: Required field '$required' not found in project"
    echo "Consider adding this field for full tracking support"
  fi
done

echo "Project board ready: $GITHUB_PROJECT_NUM"
```

**If gate fails:**
1. Configure missing environment variables
2. Create project board if needed
3. Add required fields (Status, Type, Priority)
4. Re-run readiness check

**Skill:** `project-board-enforcement`

---

## Step 1: Clarifying Questions

Before scoping, understand the request:

### Essential Questions

| Question | Purpose |
|----------|---------|
| "What are you trying to achieve?" | Understand the goal, not just the task |
| "What does success look like?" | Define acceptance criteria |
| "Who/what is affected?" | Identify scope of impact |
| "Are there constraints I should know about?" | Time, tech, compatibility |
| "Is this part of something larger?" | Link to existing initiatives |

### Discovery Questions (for unclear requests)

| Question | Reveals |
|----------|---------|
| "Can you walk me through how this would be used?" | User journey, edge cases |
| "What exists today?" | Starting point, migration needs |
| "What have you already tried?" | Failed approaches, constraints |
| "Is there prior art or examples?" | Design direction |

## Step 2: Scope Assessment

Evaluate the request against these criteria:

### Scope Matrix

| Factor | Trivial | Small | Large | Massive |
|--------|---------|-------|-------|---------|
| **Unknowns** | None | Few, answerable | Many, need research | Extensive, need spikes |
| **Deliverables** | 1 thing | 2-5 things | 6-20 things | 20+ things |
| **Code areas** | 1-2 files | 3-10 files | 10+ files | Multiple systems |
| **Dependencies** | None | Internal only | External services | New infrastructure |
| **Duration** | < 1 session | 1-3 sessions | 1-2 weeks | Weeks to months |
| **Criteria** | 1-2 | 3-5 | 6-15 | 15+ |

### Scope Decision

```
IF unknowns == none AND deliverables <= 2:
  → TRIVIAL: Use issue-prerequisite directly

IF unknowns == few AND deliverables <= 5:
  → SMALL: Use issue-prerequisite, maybe issue-decomposition

IF unknowns == many OR deliverables > 5:
  → LARGE: Use epic-management with research spikes

IF unknowns == extensive OR deliverables > 20 OR new_infrastructure:
  → MASSIVE: Use initiative-architecture
```

## Step 3: Route to Appropriate Workflow

### Trivial Scope

```markdown
**Assessment:** This is a trivial request (single deliverable, no unknowns).

**Next step:** Creating a single issue using `issue-prerequisite`.
```

Route to: `issue-prerequisite`

### Small Scope

```markdown
**Assessment:** This is a small request (few deliverables, minimal unknowns).

**Plan:**
1. Create parent issue for the request
2. If needed, decompose into 2-3 sub-issues
3. Begin implementation

**Next step:** Creating issue structure using `issue-prerequisite`.
```

Route to: `issue-prerequisite` → maybe `issue-decomposition`

### Large Scope

```markdown
**Assessment:** This is a large request requiring structured planning.

**Unknowns identified:**
- [ ] Unknown 1 - needs investigation
- [ ] Unknown 2 - needs research spike

**High-level deliverables:**
1. Deliverable A
2. Deliverable B
...

**Next step:** Creating epic structure using `epic-management`.
```

Route to: `epic-management` (which will create research spikes as needed)

### Massive Scope

```markdown
**Assessment:** This is a massive request requiring full initiative architecture.

**Why massive:**
- [Reason: extensive unknowns / new infrastructure / multi-system / etc.]

**Initial unknowns:**
- [ ] Does X exist?
- [ ] How does Y work?
- [ ] What are constraints of Z?

**Potential scope:**
- Multiple epics likely
- New capabilities needed
- Significant research required

**Next step:** Beginning initiative architecture using `initiative-architecture`.
```