start-design

name: start-design description: Start design for a GitHub issue - creates design doc from research/ideas, updates status to Ready argument-hint: [issue number or title] [--deep]

Start Design for a GitHub Issue

Transition an issue into the Design phase by creating a design document, seeded from existing research (or ideas), and updating the project board status to "Ready".

Input

$ARGUMENTS may contain:

• An issue number (e.g., 42 or #42) -> proceed directly to the workflow
• A title/text (non-numeric) -> offer to create a new issue with that title
• Nothing (empty) -> show available issues to pick from, or offer to create one
• The --deep flag (anywhere in arguments) -> create a directory structure instead of a single file

Extract --deep from arguments first, then process the remainder as issue number or title.

Help

If $ARGUMENTS contains --help or -h, display the following and stop — do not execute the workflow.

/start-design [#N | title] [--deep]

  Start design for a GitHub issue — creates design doc from research/ideas, updates status to Ready.

Arguments:
  #N              Issue number (e.g., 42 or #42)
  title           Text — offers to create or search
  --deep          Create directory structure instead of single file
  --help, -h      Show this help

What it does:
  1. Fetches issue (or creates one inline)
  2. Checks for research/ideas documents to seed from
  3. Creates design doc (single file or deep directory)
  4. Handles source docs (conclude/archive/leave)
  5. Updates project status to Ready

Examples:
  /start-design #42
  /start-design "Error handling overhaul" --deep
  /start-design

Handling No Issue Number

Case 1: No arguments provided

Fetch Research and Backlog items from the project. Always pipe gh project item-list directly to Python (see .claude/skills/_helpers.md Section 2):

gh project item-list 7 --owner nockawa --limit 200 --format json 2>&1 | python3 -c "
import json, sys
items = json.load(sys.stdin)['items']
for item in items:
    s = item.get('status', '')
    if s in ('Research', 'Backlog'):
        n = item.get('content', {}).get('number', '?')
        t = item.get('title', 'untitled')
        p = item.get('priority', '?')
        a = item.get('area', '?')
        print(f'#{n} | {s} | {p} | {a} | {t}')
"

Use the output to filter for items with Status = "Research" (prioritize these -- they're the ones most likely ready for design) then "Backlog". Use AskUserQuestion to present a choice:

Question: "Which issue would you like to start designing?" Header: "Issue" Options (up to 4, prioritize Research items first, then Backlog by priority):

• #<number> - <title> (description: "[Status] [Priority] [Area]") -- for each candidate issue
• Create a new issue (description: "I'll help you create one right now")

If the user picks an existing issue, continue with the normal workflow below using that issue number.

If the user picks "Create a new issue", proceed to Inline Issue Creation below.

Case 2: Non-numeric argument (looks like a title)

If $ARGUMENTS (after removing --deep) is not empty and not a number (doesn't match ^\d+$ after stripping #), use AskUserQuestion:

Question: "It looks like you provided a title instead of an issue number. Would you like to:" Header: "Action" Options:

• Create a new issue with this title (description: "I'll create '$ARGUMENTS' and start design on it")
• Search existing issues (description: "Search for issues matching '$ARGUMENTS' to pick one")

If "Create a new issue": proceed to Inline Issue Creation with the title pre-filled.

If "Search existing issues": use mcp__GitHub__search_issues with q: "repo:nockawa/Typhon $ARGUMENTS" and present matching issues via AskUserQuestion.

Inline Issue Creation

When an issue needs to be created, do it inline rather than redirecting the user to /create-issue.

Follow the /create-issue skill workflow directly:

1. Gather info -- Use AskUserQuestion to collect:

   • Title (if not already provided from $ARGUMENTS)
   • Description (ask the user to describe what needs to be done)
   • Type labels, Area, Priority, Phase, Estimate (use the same questions as /create-issue)

2. Create the issue -- Use mcp__GitHub__create_issue with:

   • owner: "nockawa"
   • repo: "Typhon"
   • title: "<title>"
   • body: "<description>"
   • labels: ["<label1>", "<label2>"]
   • assignees: ["nockawa"]

3. Add to project and set fields -- Follow /create-issue steps 3-5

4. Continue -- Once the issue is created, continue with the normal /start-design workflow below using the new issue number.

Workflow

1. Fetch Issue Details

Use mcp__GitHub__get_issue with:

• owner: "nockawa"
• repo: "Typhon"
• issue_number: <number>

2. Status Guard

Check the issue's current project status. If the issue is already past "Ready" (i.e., status is "In Progress", "Review", or "Done"), warn the user:

Question: "Issue # is already at ''. Starting design would move it back to 'Ready'. Proceed?" Header: "Status" Options:

• Proceed anyway (description: "Move status back to Ready and create the design doc")
• Cancel (description: "Don't change anything")

If "Cancel", stop and report that no changes were made.

3. Check for Existing Source Documents

3a. Research documents

List all files under claude/research/:

Glob: claude/research/**/*.md

If any research documents exist, present them to the user via AskUserQuestion:

Question: "I found these research documents. Which ones (if any) should feed into this design?" Header: "Research" Options (up to 4, pick the most likely related ones based on name/path similarity to the issue title):

• claude/research/<path> (description: first line or title from the file) -- for each candidate
• None (description: "Don't use any research docs") MultiSelect: true

If the user selects one or more research docs, read their full content for use in step 5.

3b. Ideas documents (if no research was selected)

If the user selected "None" for research docs (or no research docs exist), also check claude/ideas/:

Glob: claude/ideas/**/*.md

If any ideas documents exist, present them the same way:

Question: "No research docs selected. I found these ideas documents. Use any as input?" Header: "Ideas" Options (up to 4):

• claude/ideas/<path> (description: first line or title from the file) -- for each candidate
• None -- start fresh (description: "Create the design doc from scratch using only the issue context") MultiSelect: true

If the user selects ideas docs, read their full content for use in step 5.

4. Determine Design Doc Location

First, try to infer the category from the selected source document(s):

• If one or more research/ideas docs were selected, use their parent directory path as the category.
  • Example: research doc at claude/research/database-engine/QuerySystem.md -> category = database-engine/
  • Example: research doc at claude/research/timeout/README.md -> category = root level, doc name derived from issue
  • If multiple source docs are from different categories, use the most specific common ancestor.

If no category can be inferred (no source docs selected, or docs are at root level with no clear category), ask the user:

List existing directories under claude/design/ and present:

Question: "Where should this design doc go?" Header: "Location" Options (up to 4):

• design/ (root level) (description: "No category, just a file at the top level")
• design/<existing-category>/ (description: "Existing category") -- for each existing subdirectory
• Other (description: "Specify a custom path / create new category") MultiSelect: false

5. Create Design Document

Derive the document name from the issue title, using PascalCase (e.g., issue "Add spatial indexing support" -> SpatialIndexingSupport).

When source documents were selected, read their content to seed specific sections. The design doc is a scaffold -- pre-fill what can be derived, leave the actual design work to the user.

Standard Mode (no --deep)

Create a single file: claude/design/<category>/<Name>.md

# <Issue Title> Design

**Date:** <today YYYY-MM-DD>
**Status:** Draft
**GitHub Issue:** #<number>
**Branch:** --

## Summary

<If a research doc was used and has a Recommendation section, synthesize a 2-3 sentence summary from it. If an ideas doc was used, derive from its "The Idea" section. If starting fresh, derive from the issue body.>

## Goals

<If a research doc was used, extract goals from its Recommendation/Conclusion. If an ideas doc was used, extract from "Why This Might Matter". Otherwise, derive from the issue body. Format as bullet list.>
- Goal 1
- Goal 2

## Non-Goals

- [Explicitly out of scope -- to be filled by user]

## Design

### Overview

[High-level description with diagram if helpful]

### Data Structures

[Key types, schemas, storage]

### API / Interface

[Public API, method signatures]

### Implementation Details

[Key algorithms, edge cases, error handling]

## Testing Strategy

- [ ] Unit tests for X
- [ ] Integration tests for Y

## Open Questions

<If source docs had unresolved questions, migrate relevant ones here. Otherwise leave placeholders.>
- [ ] [Open question]

## References

- GitHub Issue: #<number>
<If research doc was used:>
- Research: `claude/research/<path>`
<If ideas doc was used:>
- Ideas: `claude/ideas/<path>`
<If issue body has links:>
- [Extracted references]

Deep Mode (--deep)

Create a directory: claude/design/<category>/<Name>/

README.md (entry point):

# <Issue Title> Design

<One-line description derived from summary>

**Date:** <today YYYY-MM-DD>
**Status:** Draft
**GitHub Issue:** #<number>
**Branch:** --

## Summary

<Same as standard mode -- synthesized from source docs or issue body.>

## Goals

<Same as standard mode.>

## Non-Goals

- [Explicitly out of scope -- to be filled by user]

## Document Series

| Part | Title | Focus |
|------|-------|-------|
| [01](./01-overview.md) | **Overview & Data Structures** | High-level design, key types |

## Open Questions

<Migrated from source docs or placeholders.>
- [ ] [Open question]

## References

- GitHub Issue: #<number>
<If research doc was used:>
- Research: `claude/research/<path>`
<If ideas doc was used:>
- Ideas: `claude/ideas/<path>`

01-overview.md (first part):

# Overview & Data Structures

## Design Overview

[High-level description with diagram if helpful]

## Data Structures

[Key types, schemas, storage]

## API / Interface

[Public API, method signatures]

## Implementation Details

[Key algorithms, edge cases, error handling]

## Testing Strategy

- [ ] Unit tests for X
- [ ] Integration tests for Y

Additional numbered parts can be added later with "add new part