Nnn

NNN - Next Task Planning (Hybrid: Gemini 2.5 Pro + Claude Review)

Purpose

Create a comprehensive implementation plan using a cost-optimized hybrid approach:

1. Gemini 2.5 Pro generates initial plan (fast, cheap)
2. Claude Sonnet reviews quality and improves if needed
3. Saves 75-90% cost vs Claude-only

Hybrid Approach (Phase 2 Optimization)

When to Use

• User explicitly types nnn (uses latest context or open issue)
• User types nnn #123 (uses specific issue)
• Starting a new feature or bug fix
• Need a detailed roadmap before implementation

Steps

Step 0: Generate Initial Plan with Gemini 2.5 Pro

Execute planning script:

python3 scripts/nnn_planning.py [issue_number] --mode gemini

This will:

• Fetch issue details from GitHub
• Gather current context (branch, commits, status)
• Generate comprehensive plan with Gemini 2.5 Pro
• Output plan to stdout

What you'll get:

• Complete plan in Markdown format
• All required sections (Overview, Goals, Architecture, Phases, etc.)
• Cost: ~$0.005-0.01 (vs $0.03-0.05 for Claude)

Step 1: Review Gemini's Plan Quality

Read the generated plan and score it objectively on 1-10:

Scoring Criteria:

• 10/10: Perfect - Clear, detailed, implementable, well-structured
• 8-9/10: Good - Minor improvements needed but usable
• 6-7/10: Acceptable - Needs some refinement
• 4-5/10: Poor - Missing key details or unclear
• 1-3/10: Bad - Incomplete or incorrect

Check for:

• ✅ All required sections present
• ✅ Specific, actionable tasks with checkboxes
• ✅ Realistic time estimates
• ✅ Clear deliverables per phase
• ✅ File paths and technical details
• ✅ Success criteria defined
• ✅ Phases broken into 1-2 hour chunks

Step 2: Decision - Use or Improve

If score >= 8/10:

✅ Quality acceptable - Use Gemini's plan

Create GitHub issue directly with the generated plan.
Add footer: "Generated with Gemini 2.5 Pro (reviewed by Claude, score: X/10)"

If score < 8/10:

⚠️ Quality needs improvement - Claude review

Take Gemini's plan as a starting point and:
1. Identify specific weaknesses
2. Improve those sections
3. Keep good parts from Gemini
4. Create final plan combining both

Add footer: "Generated with Gemini 2.5 Pro + Claude review (score: X/10 → improved)"

Step 3: Create GitHub Issue

Use gh issue create with the final plan (either Gemini's or improved version).

Cost tracking footer:

---
📝 Generated by: [Gemini 2.5 Pro | Gemini 2.5 Pro + Claude review]
⏰ Created: [timestamp GMT+7]
✅ Quality score: X/10
💰 Cost: ~$X.XX (savings: XX% vs Claude-only)

Fallback: If Gemini Script Fails

If scripts/nnn_planning.py errors or Gemini unavailable:

1. Fall back to Claude Sonnet (original method)
2. Follow original planning steps (below)
3. Note: This uses more tokens but ensures planning always works

Original Planning Method (Fallback)

Original Step 1: Check for Recent Context

Look for the most recent context issue (label: "context"):

gh issue list --label "context" --limit 1 --json number,title,createdAt

If no recent context exists (<2 hours old):

• Tell user: "No recent context found. Running ccc first..."
• Execute the ccc skill
• Then continue with planning

2. Gather All Context

If user specified issue number (nnn #123):

gh issue view 123

If using latest context:

# Get latest context issue
CONTEXT_ISSUE=$(gh issue list --label "context" --limit 1 --json number --jq '.[0].number')
gh issue view $CONTEXT_ISSUE

Also gather:

# Parallel execution
git status --porcelang
git log --oneline -10
gh issue list --state open --limit 10
gh pr list --state open --limit 5

3. Deep Analysis

Read context and analyze:

• What is the problem or feature request?
• What files/components are affected?
• What patterns exist in the codebase?
• What are the technical constraints?
• What are potential risks?

Use tools:

• Glob to find relevant files
• Grep to search for patterns
• Read to understand existing code
• Never execute or modify code - read only!

4. Create Comprehensive Plan Issue

Create a detailed plan issue with this template:

# Plan: [Feature/Fix Description]

## Problem Statement
[Clear description of what needs to be solved]

## Research & Analysis

### Current State
- [What exists now]
- [How it currently works]
- [Relevant code locations]

### Affected Components
- `file/path.ts` - [what needs to change]
- `other/file.py` - [why it's affected]

### Patterns & Conventions
- [Pattern 1 observed in codebase]
- [Convention to follow]

### Technical Constraints
- [Constraint 1]
- [Dependency or limitation]

## Proposed Solution

### Approach
[High-level description of the solution]

### Architecture
[How components will interact]

### Trade-offs
**Pros:**
- [Benefit 1]
- [Benefit 2]

**Cons:**
- [Limitation 1]
- [Risk 1]

## Implementation Plan

### Phase 1: [Phase Name] (~1 hour)
- [ ] Step 1: [Specific action]
- [ ] Step 2: [Specific action]
- [ ] Step 3: [Test/verify]

### Phase 2: [Phase Name] (~1 hour)
- [ ] Step 1: [Specific action]
- [ ] Step 2: [Specific action]

### Phase 3: [Final Phase]
- [ ] Integration testing
- [ ] Documentation updates
- [ ] PR creation

## Testing Strategy
- [ ] Unit tests for [component]
- [ ] Integration tests for [flow]
- [ ] Manual testing: [scenarios]

## Risks & Mitigation
- **Risk 1**: [Description]
  - **Mitigation**: [How to handle]
- **Risk 2**: [Description]
  - **Mitigation**: [How to handle]

## Success Criteria
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]
- [ ] [Performance/quality requirement]

## Related Issues
- Context: #[context-issue]
- Depends on: #[issue] (if any)
- Related: #[issue] (if any)

Use this command:

gh issue create --label "plan" --title "Plan: [Brief description]" --body "[generated content]"

5. Provide Summary

Tell the user:

✅ Analysis complete!

Plan created: #[issue-number]

**Summary:**
- [Key finding 1]
- [Key finding 2]
- [Estimated effort: X hours in Y phases]

**Next step:** Use `gogogo` to execute this plan

**Or customize:** Review and edit the plan in GitHub first

Important Notes

• NO CODING: This skill only analyzes and plans
• Comprehensive: Better to over-plan than under-plan
• Phases: Break work into ~1 hour chunks
• Context First: Always check for context, create if missing
• Label: Always add "plan" label
• Estimate: Provide realistic time estimates
• Be Honest: Flag uncertainties and risks

Success Criteria

• ✅ Plan issue created with all required sections
• ✅ Issue has "plan" label
• ✅ Implementation broken into phases (~1 hour each)
• ✅ Testing strategy defined
• ✅ Risks identified with mitigations
• ✅ User provided with clear summary and next steps

💰 Cost Impact (Phase 2 Optimization)

Before (Claude-only):

• Model: Claude Sonnet
• Cost per plan: $0.03-0.05
• Time: 2-5 minutes

After (Gemini + Claude review):

Expected Performance:

• Quality: 8-9/10 average (Gemini plans are good!)
• Review rate: ~20% (only 1 in 5 needs Claude improvement)
• Overall savings: 70-80% compared to Claude-only

🎯 Success Criteria

A good plan must have:

• ✅ Clear problem statement and goals
• ✅ Detailed technical architecture
• ✅ Implementation phases (1-2 hour chunks)
• ✅ Specific deliverables per phase
• ✅ Success criteria and testing approach
• ✅ Risk assessment and mitigation
• ✅ Realistic timeline estimates

🔧 Technical Notes

Gemini 2.5 Pro Advantages:

• Better reasoning than 1.5 Pro
• Good at structured output (plans, lists)
• Understands markdown formatting well
• 1M token context window
• Fast generation (~10-20 seconds)

When Claude Review Helps:

• Complex architectural decisions
• Project-specific patterns
• Nuanced trade-off analysis
• Deep integration considerations

⚙️ Configuration

Script options:

# Gemini only (no review)
python3 scripts/nnn_planning.py [issue] --mode gemini

# Hybrid (default, auto-review)
python3 scripts/nnn_planning.py [issue] --mode hybrid

# Claude only (fallback)
# Just use original nnn skill steps

🚨 Important Notes

• NO CODING: Planning only - never implement during this skill
• Read-only: Only read files, never modify
• Context first: Always use recent context issue if available
• Gemini first: Try Gemini script before falling back to Claude
• Be objective: Score plans fairly (don't be too lenient or harsh)
• Hybrid saves money: 70-80% savings add up quickly!