Issue Investigation & Planning Skill
Purpose
Investigate a GitHub issue thoroughly and produce a structured, actionable
implementation plan. The plan follows the project's layered architecture
(UI -> BLoC -> Repository -> Client) and includes files to modify,
implementation steps, testing strategy, and risk assessment.
Workflow
Phase 1: Fetch Issue
Retrieve the full issue context using gh CLI and GraphQL.
# Get issue details
gh issue view <number> --json title,body,comments,labels,state,assignees
# Get issue type, hierarchy, and sub-issues
gh api graphql -f query='{ repository(owner: "divinevideo", name: "divine-mobile") {
issue(number: <NUMBER>) {
id
title
body
issueType { id name }
subIssues(first: 20) { nodes { number title state } }
parentIssue { number title }
}
} }'
Determine the issue type from:
- Title prefix:
fix: = Bug, feat: = Feature, task: = Task
- GraphQL
issueType field
- Labels (e.g.,
bug label)
Extract key information:
- Bug: Steps to reproduce, actual vs expected result, environment, evidence
- Feature: Requirements, acceptance criteria, user stories
- Task: Description, scope, implementation notes
Phase 2: Explore Codebase
Search the codebase to understand the relevant code. Approach varies by type.
For Bugs
- Search for keywords from the bug description (error messages, screen names, widget names) using
Grep
- Identify the screen/page where the bug manifests using
Glob on lib/screens/ and lib/widgets/
- Trace the code path from UI through BLoC to Repository to Client
- Check for related tests using
Glob on test/
- If Nostr-related, use
mcp__nostr__read_kind or mcp__nostr__read_nip for protocol context
For Features
- Search for similar existing features using
Grep and Glob
- Identify which architectural layers are needed (new BLoC? New repository? New package?)
- Check if related models/repositories already exist in
mobile/packages/
- Look at the router (
mobile/lib/router/) for navigation integration
- If Nostr-related, use
mcp__nostr__* tools to understand relevant NIPs and event kinds
For Tasks
- Search for the specific code area mentioned in the task using
Grep
- Understand the current implementation state
- Check for existing tests that need updating
- Identify related files that might be affected
Phase 3: Analyze
For Bugs
- Identify the root cause by reading the relevant source files
- Determine which layer(s) contain the bug (UI? BLoC? Repository? Client?)
- Assess regression risk (what else could break?)
- Check if existing tests should have caught this
For Features
- Determine which layers need new code vs modifications
- Design the data flow: Client -> Repository -> BLoC -> UI
- Identify new models, events, states needed
- Consider integration with existing features (router, theme, existing BLoCs)
- Assess if any new packages are needed in
mobile/packages/
For Tasks
- Scope the change precisely
- Identify all files that need modification
- Determine if the task has cascading effects
Phase 4: Plan
Construct the implementation plan following the project's layered architecture.
Always order implementation steps bottom-up:
- Data layer changes (Client packages in
mobile/packages/)
- Repository layer changes (Repository packages in
mobile/packages/)
- Business logic changes (BLoCs in
mobile/lib/blocs/)
- Presentation layer changes (Screens/Widgets in
mobile/lib/screens/ or mobile/lib/widgets/)
- Router changes (if navigation is affected)
- Test plan (mirroring the implementation layers)
Phase 5: Output
Present the plan using the output template below.
Output Template
## Plan: [Issue Title] (#[number])
**Type**: Bug | Feature | Task
**Issue**: [URL]
**Complexity**: Low | Medium | High
---
### Issue Summary
[1-2 sentence summary in your own words after investigation]
### [Bug Only] Root Cause
- **Layer**: [UI | BLoC | Repository | Client]
- **File**: [exact file path with line numbers]
- **Cause**: [clear explanation of why this happens]
- **Evidence**: [code snippet or logic trace]
### [Feature Only] Architecture Design
- **New packages needed**: [list or "None"]
- **Layers affected**: [which of UI, BLoC, Repository, Client]
- **Data flow**: [Client -> Repository -> BLoC -> UI description]
- **Nostr events**: [relevant kinds/NIPs if applicable]
### Affected Files
| File | Action | Description |
|------|--------|-------------|
| `path/to/file.dart` | Modify / Create / Delete | What changes |
### Implementation Steps
Steps ordered bottom-up (data layer first, UI last):
1. **[Layer]: [Brief description]**
- File: `path/to/file.dart`
- Changes: [specific changes]
- Why: [rationale]
2. ...
### Testing Strategy
| Layer | Test File | What to Test |
|-------|-----------|-------------|
| [Layer] | `test/path/to/test.dart` | [specific test cases] |
### Risks and Considerations
- [Risk 1 and mitigation]
- [Risk 2 and mitigation]
Tool Reference
| Need | Tool | Example |
|---|
| Fetch issue | gh issue view | gh issue view 142 --json title,body,comments,labels |
| Issue hierarchy | gh api graphql | Sub-issues, parent issues, issue type |
| Find files by name | Glob | Glob("**/*video_feed*") |
| Search code content | Grep | Grep("VideoFeedBloc") |
| Read file details | Read | Read("mobile/lib/blocs/video_feed/video_feed_bloc.dart") |
| Check code health | mcp__dart__analyze_files | Analyze affected packages |
| Find Dart symbols | mcp__dart__resolve_workspace_symbol | Look up class/method names |
| Nostr protocol | mcp__nostr__read_nip | Check NIP specifications |
| Nostr event kinds | mcp__nostr__read_kind | Understand event structure |
Complexity Guidelines
| Complexity | Criteria |
|---|
| Low | Single layer, 1-3 files, no new models or packages |
| Medium | 2-3 layers, 4-10 files, may need new BLoC events/states |
| High | All layers, 10+ files, new packages, new models, Nostr protocol changes |
Architecture Reference
- Layer order: UI -> BLoC -> Repository -> Client
- Implementation order: Bottom-up (Client first, UI last)
- Packages:
mobile/packages/
- BLoCs:
mobile/lib/blocs/
- Screens:
mobile/lib/screens/
- Widgets:
mobile/lib/widgets/
- Router:
mobile/lib/router/
- Tests mirror:
mobile/test/ mirrors mobile/lib/
- State management: BLoC for new features, Riverpod for legacy
- Theme: Dark mode only, use
VineTheme constants
- Nostr IDs: Never truncate, always full 64-char hex