Planning Workflow

Every unit of work gets a GitHub issue. One session = one issue = one PR.

When to Create an Issue

Situation	Action
Starting new work	Create issue first
"Let's plan X"	Create detailed issue
Scope creep mid-session	Pause → ask about new issue
Quick fix / trivial change	Ask if issue needed

Session Flow

Planning Phase (plan mode active)

code

1. Understand the work
2. Draft issue content (do NOT create yet)
3. Include issue draft in plan file
4. Exit plan mode for approval

Execution Phase (after plan approval)

code

5. Create the issue (first step after approval)
6. Track issue as session context
7. Do the work (core-workflow)
8. If scope expands → STOP, ask about new issue
9. Finalize → PR closes the issue

Creating the Issue

Plan Mode: During planning, draft the issue content and include it in your plan file. Do NOT run gh issue create until after plan approval.

Before Creating

Gather all context needed to do the work:

•What problem are we solving?
•What's the approach?
•What are the acceptance criteria?
•What files/areas will be touched?
•Any risks or open questions?

Issue Titles

Use brief noun phrases describing the need, not imperative actions:

✅ Good	❌ Bad
"API rate limiting"	"Add rate limiting to API"
"User authentication flow"	"Fix authentication flow"
"Dashboard performance"	"Improve dashboard performance"

Issue Format

bash

gh issue create \
  --repo primcloud/<repo> \
  --title "Brief noun phrase" \
  --body "## Summary
What we're doing and why.

## Approach
How we'll implement this.
- Step 1
- Step 2
- Step 3

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Tests written

## Files/Areas
- \`path/to/file.ts\`
- \`path/to/other.php\`

## Notes
Any additional context, decisions, risks." \
  --project "Primcloud"

In plan mode: Include this draft in your plan file and exit plan mode. After approval: Run gh issue create as the first execution step.

After Creating

•Note the issue number and node ID
•Set issue type (Task or Bug)
•Add to project board (if not auto-added)
•Move to "In Progress"
•Store internally: "Working on #N - [title]"

Setting Issue Type

After creating an issue, set its type:

bash

# Get issue node ID
ISSUE_ID=$(gh issue view <num> --repo primcloud/<repo> --json id --jq '.id')

# Set as Task
gh api graphql -f query="
mutation {
  updateIssue(input: {
    id: \"$ISSUE_ID\",
    issueTypeId: \"IT_kwDOA_9RlM4AwYt7\"
  }) {
    issue { title issueType { name } }
  }
}"

# Or set as Bug
gh api graphql -f query="
mutation {
  updateIssue(input: {
    id: \"$ISSUE_ID\",
    issueTypeId: \"IT_kwDOA_9RlM4AwYt9\"
  }) {
    issue { title issueType { name } }
  }
}"

Type	ID	Use
Task	`IT_kwDOA_9RlM4AwYt7`	A specific piece of work
Bug	`IT_kwDOA_9RlM4AwYt9`	An unexpected problem or behavior

Session Context Tracking

Once an issue is created, track it as session context:

code

Active Issue: #123 - Add bandwidth tracking endpoint
Repo: primcloud/platform

GitHub Identity: You operate as dunnbot. Comments, issues, and PRs from that account are your previous work.

This context should be referenced:

•When making implementation decisions
•When scope questions arise
•When creating the PR

If context compaction occurs, the issue contains the full context. Fetch it:

bash

gh issue view 123 --repo primcloud/<repo>

Note: Comments from dunnbot are your previous notes. Use them to restore context.

Planning Multiple Issues

Sometimes planning reveals work that should be split into multiple issues.

When to Split

•Distinct deliverables that could merge independently
•Different areas of the codebase with no dependencies
•Work that benefits from separate review cycles

How to Handle

•Draft all issues in the plan file
•Note dependencies/order if any
•Get approval on the full set
•After approval: create all issues, pick one to start
•Other issues become backlog (or parallel work if independent)

Plan File Format

markdown

## Issue Drafts

### Issue 1: API rate limiting

Summary, approach, acceptance criteria...

### Issue 2: Rate limit dashboard

Summary, approach, acceptance criteria...

## Execution Order

1. Start with Issue 1 (no dependencies)
2. Issue 2 depends on Issue 1

Scope Creep Handling

When additional work is discovered mid-session:

•
STOP — Don't just do it
•
Assess — Is this part of the current issue or separate?

•

Ask:

code

I've discovered we also need to [X]. This seems outside the scope of #123.

Options:
1. Add to current issue (if small and related)
2. Create new issue for separate work
3. Note it and skip for now

How do you want to handle this?

•
If new issue: Create it, but don't work on it this session
•
If adding to current: Update the issue body with new scope

Updating Current Issue

bash

# View current body
gh issue view 123 --repo primcloud/<repo>

# Edit to add scope (opens editor)
gh issue edit 123 --repo primcloud/<repo>

Finalization

When work is complete and approved for commit:

1. Create PR with Issue Reference

bash

gh pr create \
  --repo primcloud/<repo> \
  --title "feat: clear description" \
  --body "## Summary
What was done.

## Changes
- Change 1
- Change 2

## Testing
- [ ] Tests pass
- [ ] Manual testing done

Closes #123"

2. Provide PR Summary

When presenting the PR:

code

PR ready to create:

Title: feat: add bandwidth tracking endpoint

Body:
## Summary
Implemented bandwidth tracking endpoint for ingress metrics.

## Changes
- Added POST endpoint at `/api/bandwidth`
- Added validation for incoming data
- Added NATS event publishing
- Added feature tests

Closes #123

The Closes #123 automatically:

•Links the PR to the issue
•Moves issue to "Done" when PR merges

Quick Commands

Action	Command
Create issue	`gh issue create --repo primcloud/<repo> --title "..." --body "..." --project "Primcloud"`
Get node ID	`gh issue view <num> --repo primcloud/<repo> --json id --jq '.id'`
Set as Task	`gh api graphql -f query='mutation { updateIssue(input: { id: "<node-id>", issueTypeId: "IT_kwDOA_9RlM4AwYt7" }) { issue { title } } }'`
Set as Bug	`gh api graphql -f query='mutation { updateIssue(input: { id: "<node-id>", issueTypeId: "IT_kwDOA_9RlM4AwYt9" }) { issue { title } } }'`
View issue	`gh issue view <num> --repo primcloud/<repo>`
Edit issue	`gh issue edit <num> --repo primcloud/<repo>`
Add comment	`gh issue comment <num> --repo primcloud/<repo> --body "..."`
Add to project	`gh project item-add 6 --owner primcloud --url <issue-url>`
Create PR	`gh pr create --repo primcloud/<repo> --title "..." --body "... Closes #N"`

Examples

Starting a Session (Plan Mode)

Josh: "Let's add rate limiting to the API"

Response (in plan file):

markdown

# Plan: API Rate Limiting

## Issue Draft

**Title:** API rate limiting

**Body:**

## Summary

Rate limiting for API endpoints to prevent abuse.

## Approach

- Use Laravel's built-in rate limiter
- Configure limits in RouteServiceProvider
- Add rate limit headers to responses
- Add tests for rate limit behavior

## Acceptance Criteria

- [ ] Rate limits applied to auth endpoints
- [ ] Rate limits applied to API endpoints
- [ ] Headers show remaining requests
- [ ] Tests cover rate limit scenarios

## Files/Areas

- `app/Providers/RouteServiceProvider.php`
- `routes/api.php`
- `tests/Feature/RateLimitTest.php`

Exit plan mode for approval.

After Plan Approval

First step: Create the issue with gh issue create, then begin work.

Scope Creep

During work: "I noticed the auth middleware also needs updating"

Response:

code

I've found that the auth middleware needs changes to support rate limiting properly. This seems related but expands the scope.

Options:
1. Add middleware update to current issue #123 (it's directly related)
2. Create separate issue for middleware refactor
3. Note it for later and keep current scope

How do you want to handle this?

Finalization

Josh: "Looks good, commit it"

Response:

code

PR ready:

Title: feat: add rate limiting to API

Body:
## Summary
Added rate limiting to prevent API abuse.

## Changes
- Configured rate limits in RouteServiceProvider
- Applied limits to auth and API routes
- Added X-RateLimit headers to responses
- Added comprehensive rate limit tests

## Testing
- All tests pass
- Manually verified rate limit headers

Closes #123

Don't

•❌ Start work without an issue
•❌ Create issue during plan mode (draft only, create after approval)
•❌ Expand scope without asking
•❌ Create PR without Closes #N
•❌ Work on multiple issues in one session
•❌ Forget to track the active issue
•❌ Amend commits unless explicitly told to