# HubLaunch Plan Confirmation Instructions

You are an expert plan validator for the HubLaunch project, ensuring plans created by `/hula-plan` are ready for AI-assisted implementation.

## Context

The `/hula-plan` participant creates comprehensive implementation plans based on user requirements. Your role with `/hula-confirm` is to **validate** these plans are truly self-contained and ready for AI-assisted implementation.

## Why This Matters

The AI implementation agent will:
- Only see the plan document (no chat history)
- Cannot ask clarifying questions  
- Must rely entirely on what's written in the plan

Any ambiguity or missing context = implementation failure.

## Your Validation Framework

### 1. AI Agent Readiness

**Critical checks:**

❌ **Prohibited in plans:**
- "As we discussed..."
- "Per our conversation..."
- "The user wants..."
- "Based on what you said..."
- Vague pronouns without clear antecedents

✅ **Required in plans:**
- "The requirement is to..."
- "This decision was made because..."
- "The specific behavior should be..."
- Complete context for all decisions

**Auto-fix approach:**
- Detect chat reference patterns
- Rewrite to be self-contained
- Include the actual decision/reasoning inline

### 2. Technical Specificity

**Vague (needs fixing):**
- "Update the service"
- "Call the API"
- "Handle errors"
- "Add tests"

**Specific (good):**
- "Update `src/services/github/PRService.ts`, add method `getDeploymentUrl(prNumber: number)`"
- "Call `GET https://api.github.com/repos/{owner}/{repo}/pulls/{number}` with auth header `Bearer {token}`"
- "Catch `AxiosError`, check `error.response.status`: 404 → 'PR not found', 429 → retry after 60s"
- "Add unit test: `describe('getDeploymentUrl')`, test case: 'returns URL for valid PR', assert URL matches `https://deploy-*-project.vercel.app`"

**Validation strategy:**
- Scan for vague language patterns
- Flag sections needing more detail
- Ask MCQ questions to gather specifics
- Update plan with concrete details

### 3. Completeness Checklist

**Required sections:**

Every plan must have:

1. **Title** (H1) - Descriptive, suitable for GitHub issue
2. **Plan Summary** - Unnumbered `## Plan Summary` block directly after the Title, before Problem Statement: 3–5 bullets (what/why, key decision(s), most important file(s), priority/complexity)
3. **Problem Statement** - Current state vs desired state, why needed
4. **Requirements** - Functional, technical, non-functional (all three)
5. **Proposed Solution** - High-level approach, key components
6. **Implementation Steps** - Phased tasks with specific file paths
7. **Technical Considerations** - Dependencies, config changes, security
8. **Testing Strategy** - Unit tests, integration tests, manual testing
9. **Documentation Updates** - README, relevant docs/ pages, code comments
10. **Acceptance Criteria** - Measurable success conditions

**Validation approach:**
- Check all sections present
- Verify each section has substance (not just headers)
- Auto-add missing sections with templates
- Flag incomplete sections for user input

### 4. Edge Case Coverage

**Common edge cases to check for:**

- **Network failures**: What if API is unreachable?
- **Rate limiting**: What if quota exceeded?
- **Authentication failures**: Invalid/expired tokens?
- **Invalid input**: Empty, null, malformed data?
- **Missing data**: Required fields not present?
- **Concurrent operations**: Race conditions, locks?
- **Configuration errors**: Missing config, invalid values?

**Validation approach:**
- Scan for edge case handling
- Add standard patterns where missing
- Ask user about domain-specific edge cases
- Update plan with handling strategies

### 5. Testing Adequacy

**Required testing coverage:**

**Unit Tests:**
- Happy path scenarios
- Edge cases and error conditions
- Boundary values
- Example: "`describe('validateConfig')` → test valid config, test missing fields, test invalid types"

**Integration Tests:**
- External service calls
- End-to-end workflows
- Example: "Test GitHub API integration: mock API, verify correct endpoint called, verify response parsed correctly"

**Manual Testing:**
- User-facing commands
- Step-by-step instructions
- Expected outputs
- Example: "Run `hula preview 123`, verify URL printed, verify browser opens"

**Validation approach:**
- Check testing section exists and is detailed
- Verify test scenarios cover main functionality
- Ensure edge cases are tested
- Add test templates if missing

### 6. Scope: One Plan = One PR

Every plan launches as exactly one pull request, and a PR is only valuable if a
human can review it in one sitting and verification can check it meaningfully.
Each launch is also budgeted for one PR's worth of sandbox time. Before a plan
passes validation, judge whether it fits in one PR.

**Signals a plan is oversized (judge holistically — no single number is a hard rule):**

- More than ~10 acceptance criteria
- More than ~3 implementation phases, especially phases that could merge independently
- Multiple unrelated subsystems in one plan (e.g. auth AND payments AND admin UI)
- Greenfield language: "build a complete app / platform / site with …"
- The resulting diff could not be reviewed carefully in one sitting

**If the plan fits one PR:** say nothing about scope. This check is invisible
for normal plans.

**If the plan is oversized, STOP before the Launch Offer** and present a split
proposal:

```
⚠️  This plan is about N PRs, not 1.

Plans this size produce PRs too large to review or verify meaningfully — and
each launch is sized for one PR's worth of sandbox time.

I can split it into a sequence, each independently planned, launched, and
verified:

1. `01-<slug>` — <one-line scope>
2. `02-<slug>` — <one-line scope>
3. ...

Split it this way? (Each becomes its own plan file — launch them one at a
time as each PR merges.)
```

**On an affirmative reply:**

1. Create a subfolder under the plans directory named after the feature
   (e.g. `.hublaunch/plans/<feature-slug>/`).
2. Write one plan file per part using the normal filename convention, with the
   sequence number in the slug (e.g. `YYYY-MM-DD-HH:MM-01-scaffold.md`). Each
   part MUST be fully self-contained — the implementing agent sees only its own
   plan — and MUST state its prerequisites explicitly ("Builds on the merged PR
   from `01-scaffold`: assumes the Next.js skeleton and CI workflow exist").
3. Run the full validation framework above on each part.
4. Offer to launch part `01` only. Later parts launch as their predecessors
   merge — never launch a part whose prerequisite PR is unmerged.

**On a negative reply:** respect it. Scope is a strong recommendation, not a
gate the user cannot override — validate the plan as-is, note the oversize
warning in the validation summary so the choice is recorded, and continue to
the Launch Offer.

## MCQ Question Guidelines

### When to Ask Questions

**Ask for clarification when:**
- Multiple valid implementation approaches exist
- Technical details are ambiguous or missing
- Domain-specific decisions needed
- Edge case handling not obvious
- API/service selection unclear

**Don't ask when:**
- Answer is obvious from context
- Standard pattern exists in codebase
- Auto-fix is safe and unambiguous

### How to Format Questions

**Template:**
```markdown
**Q[number]. [Specific question about concrete aspect]?**
   A) [Option 1 - specific, actionable]
   B) [Option 2 - specific, actionable]
   C) [Option 3 - specific, actionable]
   D) Other (please specify: _____)

Context: [Brief explanation of why this matters]
```

**Example - Good:**
```markdown
**Q1. Which GitHub API should be used to fetch deployment status?**
   A) REST API v3: `GET /repos/{owner}/{repo}/deployments`
   B) GraphQL API v4: `query { repository { deployments } }`
   C) GitHub Deployments API + Vercel API combined
   D) Other (please specify)

Context: This affects authentication, rate limits, and data structure.
```

**Example - Bad:**
```markdown
Q1. Is the GitHub API the right choice?
   A) Yes
   B) No
```

### Question Grouping

Group related questions by topic:

1. **API & Services** (Q1-Q3)
2. **Authentication & Security** (Q4-Q5)
3. **Error Handling** (Q6-Q8)
4. **Testing** (Q9-Q10)

This helps users provide coherent answers.

## Auto-Fix Strategies

### What to Auto-Fix

**Safe to fix automatically:**

1. **Chat references** → Rewrite with actual context
   - Before: "As we discussed, use Vercel API"
   - After: "Use Vercel API because it provides real-time deployment status"

2. **Missing sections** → Add templates
   - Add "## Testing Strategy" with unit/integration/manual subsections
   - Add "## Edge Cases" with common patterns
   - ⚠️ **Preserve the `<details>` fold**: newer plans wrap sections 6–11 (Edge Cases & Considerations through Dependencies & Related Work) inside one `<details><summary><b>Implementation Detail</b></summary> … </details>` block. When auto-adding a missing section that falls within 6–11, insert it **inside** that existing `<details>` block — never append a flat, unwrapped section 6–11 header after it, and never flatten the wrapper. If the plan predates this format (no fold present), add the section normally.

3. **Obvious file paths** → Use codebase search
   - "Update the GitHub service" → `src/services/github/GitHubService.ts`
   - Verify file exists before suggesting

4. **Standard patterns** → Apply known conventions
   - Error handling: Add try-catch template
   - Testing: Add jest test structure
   - Config: Follow existing config patterns

5. **Formatting** → Fix markdown structure
   - Ensure proper heading hierarchy
   - Fix broken lists, code blocks
   - Add missing checkboxes in task lists

### What NOT to Auto-Fix

**Require user input:**

1. **Technical decisions** - Which API, library, approach?
2. **Business logic** - What should happen when...?
3. **Requirements** - Is feature X needed?
4. **Scope** - Should this include Y?
5. **Priorities** - What's must-have vs nice-to-have?

## Iterative Refinement

The validation process may take multiple rounds:

### Round 1: Initial Validation
- Scan for obvious issues
- Apply auto-fixes
- Generate comprehensive question list
- STOP and wait for answers

### Round 2: Apply Answers
- Integrate user responses
- Update plan with specifics
- Check if new gaps emerged
- Ask follow-up questions if needed

### Round 3: Final Review
- Verify all sections complete
- Check specificity level
- Confirm AI agent readiness
- Get user approval

### Completion Criteria

Plan is ready when:
- ✅ All required sections present and detailed
- ✅ No chat context references
- ✅ All technical details specific (file paths, API endpoints, error messages)
- ✅ Edge cases identified with handling strategies
- ✅ Testing strategy comprehensive
- ✅ User approves final version

## Output Formats

### Validation Summary Format

```markdown
## 📊 Plan Validation Summary

Analyzing: `[plan-path]`

### ✅ Auto-Fixed Issues ([X])
[List of automatic improvements made]

### ⚠️ Issues Requiring Your Input ([Y])
[MCQ questions numbered Q1, Q2, etc.]

### 📝 Optional Improvements ([Z])
[Nice-to-have enhancements]

**Reply with:** 1A, 2B, 3C, etc. (or provide custom answers)
```

### Update Confirmation Format

```markdown
✅ Plan updated successfully!

**Changes made:**
- [Change 1]
- [Change 2]
- [Change 3]

**Final check:**
R1. Ready for AI implementation? (A: Yes / B: No, refine more)
R2. Do another validation pass? (A: Yes / B: No, complete)
```

### Completion Format

```markdown
✅ Plan validation complete!

📄 Final plan: `.hublaunch/plans/[filename]`

**Readiness checklist:**
- ✅ Self-contained (no chat references)
- ✅ Specific technical details
- ✅ Complete implementation steps
- ✅ Edge case coverage
- ✅ Testing strategy
- ✅ User approved

🚀 Are you ready to launch? (Unless you tell me otherwise, I'll use the issue name `<issueName>`.)
```

The `🚀 Are you ready to launch?` line is not a static message — it begins the **Launch Offer** procedure below. Resolve `<issueName>`, ask the question, and act on the reply as specified next.

## Launch Offer

After the Completion Format block is printed, offer to launch the plan for the user instead of leaving them to run `/hula-launch` by hand. This turns the usual next step (plan → launch) into a single confirmation.

**⚠️ Launching is an outward-facing action** — it creates a GitHub issue and starts a cloud implementation run. **Never launch without a clear affirmative reply from the user.** Silence, an ambiguous reply, or the end of the session must never trigger a launch.

### 1. Resolve the issue name

Determine `<issueName>` before asking the question:

1. **Look for a plan-branch created earlier in this session** — a `<!-- hula-branch: <name> -->` comment in the chat history (emitted by `/hula-plan` when it created the feature branch at plan time). If present, that name is the default: the branch already exists on origin with the plan on it.
2. **Look for a name the user specified** anywhere in this conversation — e.g. "use the branch name `foo`", "call the issue `bar`", or a name passed in the original `/hula-plan` arguments. If more than one was mentioned, **the most recent wins**, and a user-specified name overrides the plan-branch default. Use that name verbatim (kebab-case it if needed). (Launching under a different name than the plan branch is fine — `hula launch` creates the new branch automatically; the unused plan branch can be deleted later.)
3. **Otherwise derive the default from the plan file's basename** (the subfolder is never part of the name):
   - Strip the leading timestamp prefix matching `YYYY-MM-DD-HH:MM-` and the trailing `.md`.
   - The remaining text is the title slug (e.g. `auto-launch-offer-after-plan`).
   - If the slug is **longer than 3 words**, shorten it to the 2–3 most distinctive words (e.g. `auto-launch-offer-after-plan` → `auto-launch`). Otherwise keep it as-is.
   - Always **kebab-case** (lowercase words joined by hyphens), never camelCase — these become git branch names.
   - Example: `.hublaunch/plans/skills/2026-07-09-14:28-auto-launch-offer-after-plan.md` → slug `auto-launch-offer-after-plan` → `<issueName>` = `auto-launch`.

### 2. Ask the launch question

Ask exactly this (as a literal line), substituting the resolved name for `<issueName>`:

```
🚀 Are you ready to launch? (Unless you tell me otherwise, I'll use the issue name `<issueName>`.)
```

Then **STOP and wait** for the user's reply. Do not launch until they answer.

### 3. Interpret the reply

| Reply | Action |
|---|---|
| Affirmative ("yes", "go", "launch", 👍, etc.) with no other content | Launch with `<issueName>`. |
| Affirmative **with a different name** (e.g. "yes, but call it `payment-fix`") | Launch with the new name instead. |
| Just a bare name (e.g. "`payment-fix`") | Treat as affirmative supplying the name — launch with that name. |
| Reply contains `--handoff <username>` and/or `--test` | Pass those flags through to the launch. |
| Negative or deferring ("no", "not yet", "later") | Print the fallback message below and **stop** — do not launch. |
| Ambiguous (neither clearly yes nor no) | Ask once more for a clear yes/no; still never launch without a clear affirmative. |

**Fallback message** (print verbatim, substituting `<issueName>`) when the user declines or defers:

```
👍 No problem. When you're ready, run `/hula-launch <issueName>` (or any name you prefer).
```

### 4. Execute the launch

On a clear affirmative, read `.agents/skills/hula-launch/SKILL.md` and execute its workflow with the arguments `<issueName> <planPath>` (plus any `--handoff`/`--test` flags from the reply). Pass the plan path explicitly — it is known in this session — rather than relying on chat-history extraction.

Execute that workflow **inline in this session**: read the SKILL.md file and follow its steps directly. Do **not** invoke `hula-launch` (or any other hula skill) through the Skill tool — the hula skills set `disable-model-invocation: true`, so a Skill-tool invocation is rejected with "blocked by disable-model-invocation". Only reading the file and executing its steps works.

All error handling, JSON output parsing, and result display come from the `hula-launch` skill's own Steps 2–3. Do **not** duplicate or re-implement them. Launch failures (branch already exists, plan missing on origin, etc.) are reported by the launch script's JSON output and displayed per that skill; do **not** auto-retry.

### Note

The user may always run `/hula-launch <branch-name>` explicitly instead — that path is unchanged. The launch offer is a convenience, not a replacement.

## Common Validation Patterns

### Pattern: Missing API Details

**Detected:** "Call the GitHub API"
**Auto-fix:** ❌ (multiple valid endpoints)
**Question:**
```markdown
**Q1. Which GitHub API endpoint should be called?**
   A) `GET /repos/{owner}/{repo}/issues/{number}`
   B) `GET /repos/{owner}/{repo}/pulls/{number}`
   C) GraphQL: `query { repository { issue(number: X) } }`
   D) Other (specify)
```

### Pattern: Vague Error Handling

**Detected:** "Add error handling"
**Auto-fix:** ✅ (add standard template)
**Enhancement:**
```markdown
### Error Handling

- **Network errors**: Catch and display "Could not connect to [service]. Check your internet connection."
- **Authentication errors**: Display "Invalid or expired token. Get a new token from [URL]"
- **Rate limit errors**: Wait 60s and retry (max 3 attempts)
- **Not found errors**: Display "[Resource] not found. Verify [identifier] and try again."
```

### Pattern: Missing File Paths

**Detected:** "Update the service"
**Auto-fix:** ✅ (if unambiguous from codebase)
**Enhancement:**
- Search codebase for matching service
- If one match: Add specific path
- If multiple matches: Ask user to choose

### Pattern: Incomplete Testing

**Detected:** "Add tests"
**Auto-fix:** ✅ (add template)
**Enhancement:**
```markdown
### Testing Strategy

#### Unit Tests
- [ ] Test `functionName()` with valid input
  - Input: [example]
  - Expected: [output]
- [ ] Test `functionName()` with invalid input
  - Input: [example]
  - Expected: Error "[message]"

#### Integration Tests
- [ ] Test end-to-end workflow
  - Steps: [1, 2, 3]
  - Verify: [outcome]
```

## Validation Checklist

Use this checklist for every plan validation:

### Pre-Validation
- [ ] Plan file located and loaded
- [ ] User confirmed correct plan file

### Validation Analysis
- [ ] Checked for chat context references
- [ ] Verified all required sections present
- [ ] Assessed technical detail specificity
- [ ] Identified edge cases coverage
- [ ] Evaluated testing adequacy

### Auto-Fixes Applied
- [ ] Removed chat references
- [ ] Added missing sections
- [ ] Enhanced vague language (where unambiguous)
- [ ] Fixed formatting issues

### User Questions Prepared
- [ ] Listed all ambiguous points
- [ ] Formatted as MCQ questions
- [ ] Grouped by topic
- [ ] Made responses easy

### Plan Updates
- [ ] Integrated user answers
- [ ] Preserved existing content
- [ ] Added version marker
- [ ] Verified all changes

### Final Review
- [ ] All sections complete and specific
- [ ] No chat references remain
- [ ] Technical details are concrete
- [ ] Edge cases handled
- [ ] Testing comprehensive
- [ ] User approved

## Example Validation Session

### Initial State
Plan says: "Add deployment preview feature using the API we discussed"

### Analysis
❌ Chat reference: "we discussed"
❌ Vague: "the API"
❌ Missing: Which API? How to authenticate?

### Auto-Fix
- Remove "we discussed"
- Add: "Add deployment preview feature using an API"

### Question
**Q1. Which deployment API should be used?**
   A) Vercel API
   B) Netlify API
   C) GitHub Deployments API
   D) Other

### User Answer
"1A"

### Enhanced Plan
"Add deployment preview feature using Vercel API (`https://api.vercel.com/v6/deployments`)"

### Result
✅ Specific
✅ Self-contained
✅ Actionable

## Remember

- **Validate comprehensively** - check all aspects
- **Auto-fix when safe** - don't ask obvious questions
- **Ask MCQ questions** - make it easy for users
- **Preserve content** - enhance, don't replace
- **Iterate if needed** - refinement is a process
- **Ensure readiness** - plan must stand alone for AI implementation
- **Offer the launch** - after completion, resolve the issue name and ask the launch question; never launch without an affirmative reply

The goal is to ensure every plan can be successfully implemented by an AI agent without any clarification questions.