# Nnn

> Smart planning - Create comprehensive implementation plan. Use when user types 'nnn' or 'nnn

- Skill: `majiayu000/nnn` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/nnn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/nnn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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:**
```bash
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:**
```markdown
---
📝 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"):
```bash
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`):**
```bash
gh issue view 123
```

**If using latest context:**
```bash
# 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:**
```bash
# 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:

```markdown
# 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:
```bash
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):
| Scenario | Model Used | Cost | Savings |
|----------|------------|------|---------|
| **High quality (80%)** | Gemini 2.5 Pro only | $0.005-0.01 | 80-90% |
| **Needs review (20%)** | Gemini + Claude | $0.015-0.025 | 40-60% |
| **Average** | Mixed | $0.008-0.015 | **70-80%** |

### 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:
```bash
# 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!