task-prd-creator

What this skill does

# Task & PRD Creator

Write a clear, actionable PRD or task. Output depends on where the user tracks work.

## Contract

Inputs:

- Feature, bug, enhancement, or planning request
- Destination preference: GitHub issue, local PRD/task file, or both
- Optional parent issue, labels, assignee, and priority

Outputs:

- Draft PRD or task body
- Destination-specific create command or file path
- Created issue/file URL or path after approval

Creates/Modifies:

- Local `.agents/memory/<kebab-name>.md` PRD files only after draft approval
- GitHub issues/sub-issues only after draft approval

External Side Effects:

- Reads GitHub issue state
- May create GitHub issues, sub-issues, or issue branches

Confirmation Required:

- Always show the draft before creating files or GitHub issues
- Ask before linking sub-issues or creating issue branches

Delegates To:

- `spec-first` when implementation constraints are still unclear
- `tdd` when the work should be executed test-first
- `gh-fix-ci` for CI failures after implementation
- `strategy-expert` for roadmap-level planning

## Step 1: Detect workflow preference

Check in order:

1. User explicitly says "GitHub issue", "local file", or both
2. Check if `gh auth status` succeeds and a GitHub remote exists → GitHub available
3. If ambiguous, ask: "GitHub issue, local PRD file in `.agents/memory/`, or both?"

## Step 2: Understand the request

Ask only what's missing — don't interrogate if context is clear:

- What problem does this solve?
- Who's affected? (user-facing, internal, infra)
- Any hard constraints or dependencies?
- Is this part of a larger epic? (→ sub-issue)
- Priority: critical / high / medium / low

## Step 3: Research before writing

- Read relevant architecture docs if available (`.agents/memory/` — look for architecture, summary, or context files)
- Search codebase for related patterns
- Check for existing issues on same topic: `gh issue list --search "[keyword]"`

## Step 4: Write the PRD

See `references/full-guide.md` for the full PRD structure.

A good PRD has:

- **Problem** — why this exists, what breaks without it
- **Goal** — one sentence, measurable outcome
- **Scope** — what's in, what's explicitly out
- **Acceptance criteria** — testable, not vague
- **Technical notes** — approach, risks, dependencies

Keep it tight. No filler. Acceptance criteria must be checkable by a human.

### Agent-ready issue rules

When the output is an issue for an autonomous or AFK agent, write it as an
agent brief, not a stream-of-consciousness plan:

- Describe behavior and contracts, not file-by-file instructions.
- Avoid line numbers and brittle file paths unless the path is itself the contract.
- Include current behavior, desired behavior, acceptance criteria, and out of scope.
- Name public interfaces, CLI commands, API shapes, config keys, or data contracts when known.
- Keep implementation notes as constraints, not a script the agent must follow.

### Vertical-slice breakdown

When breaking an epic, PRD, or plan into issues:

- Prefer thin vertical slices that produce a verifiable outcome.
- Mark each issue as `AFK` when an agent can complete it without more human input.
- Mark each issue as `HITL` when it needs a human decision, design review, credential, or product judgment.
- Publish blockers before blocked issues so dependencies can reference real issue IDs.
- Keep each sub-issue small enough for one focused PR.

## Step 5: Output to correct destination

### GitHub (primary if available)

**New issue:**

```bash
gh issue create \
  --title "[type]: clear title" \
  --body "$(cat <<'BODY'
[PRD content here]
BODY
)" \
  --label "feature" \
  --assignee "@me"
```

**Sub-issue** (linked to parent):

```bash
# Create sub-issue
gh issue create --title "..." --body "..." 

# Link as sub-issue to parent #N
gh issue develop N --checkout  # only if needed
# Use: gh api repos/{owner}/{repo}/issues/{parent}/sub_issues --method POST -f sub_issue_id={child_id}
```

**Draft PR from issue:**

```bash
gh issue develop [issue-number] --branch "feature/[name]"
```

### Local files (optional, or when no GitHub)

- PRD: `.agents/memory/[kebab-name].md`

See `references/full-guide.md` for local file templates.

## Step 6: Get approval before creating

Show the draft PRD. Wait for "looks good" or edits. Then create.

## Rules

- `disable-model-invocation: true` → only runs when user explicitly invokes
- Never create files or GitHub issues without user seeing the draft first
- Sub-issues should be small enough to ship in one PR
- If requirements are unclear, write the problem statement first — not the solution
- If rejecting an enhancement as out of scope, record durable reasoning in `.out-of-scope/<concept>.md` when the repo uses local out-of-scope memory.

## Related

- `spec-first` — spec-driven development before writing code
- `tdd` — red-green-refactor execution for tasks with clear behavior
- `gh-fix-ci` — fix CI on existing PRs
- `strategy-expert` — broader roadmap and content planning