gastrobrain-product-strategy-health

name	Gastrobrain Product Strategy & Health
description	Strategic partner for roadmap planning, priority setting, and project health management. Provides 'wide picture' perspective balancing feature development with code quality, technical debt, and long-term sustainability. Use for: 'Review the roadmap', 'Help me prioritize', 'Is my milestone balanced?', 'Should I focus on features or quality?', 'Strategic review of 0.X.Y'.
version	1.1.0
author	Gastrobrain Development Team

Gastrobrain Product Strategy & Health

A strategic guidance skill that acts as a combined Product Owner and Tech Lead for Gastrobrain. Provides strategic roadmap planning, priority setting, and project health management to ensure sustainable development that balances user value with technical excellence.

The Strategic Partner Role

What This Skill Provides

This skill acts as your strategic partner who:

• Sees the big picture beyond individual sprints and tasks
• Balances competing demands between features, quality, and technical debt
• Ensures sustainable velocity through regular refactoring and testing time
• Prevents "feature factory" syndrome where quality work gets neglected
• Thinks long-term about architectural evolution and project health
• Validates priorities strategically beyond just user requests
• Recommends when to pause features for dedicated quality sprints
• Keeps technical debt from accumulating to unsustainable levels

The Missing Role

As a solo developer, you need someone who can:

• Challenge your roadmap when it's unbalanced
• Force strategic thinking about priorities
• Ensure code quality doesn't get sacrificed for features
• Plan technical debt reduction proactively
• Think about architectural sustainability
• Balance short-term delivery with long-term health

This skill fills that role.

When to Use This Skill

Trigger Patterns

Invoke this skill when you say:

• "Review the roadmap"
• "Help me prioritize the backlog"
• "Is my milestone balanced?"
• "Should I focus on features or quality?"
• "What should I work on next?"
• "Strategic review of 0.X.Y"
• "Planning next quarter"
• "Is it time for a tech debt sprint?"
• "Evaluate project health"
• "Help me plan the next phase"

Data Sources

GitHub Project #3 (owner: alemdisso) is the single source of truth for issue estimates and project status.

# Fetch ALL project items with estimates, size, priority, status, milestone
gh project item-list 3 --owner alemdisso --format json --limit 100

# Fetch open milestones for roadmap overview
gh api repos/alemdisso/gastrobrain/milestones?state=open --jq '.[] | {number: .number, title: .title, open: .open_issues, closed: .closed_issues, description: (.description[:200])}'

# Fetch issues for a specific milestone
gh issue list --milestone "0.1.X" --state all --json number,title,labels,state

Key Project fields: estimate (story points), size (XS/S/M/L/XL), priority (P1/P2/P3), status (Ready/In Progress/Done), milestone

Sprint velocity reference: docs/archive/Sprint-Estimation-Diary.md — cruising velocity is 20 points/week

Documentation Paths

When this skill creates or references documents, use these paths:

Document Type	Path
Milestone roadmap	docs/planning/milestones/roadmap-{version}.md
Sprint plan	docs/planning/sprints/sprint-planning-{version-or-dates}.md
Sprint diary entries	docs/archive/Sprint-Estimation-Diary.md

See docs/README.md for the complete documentation decision tree.

Automatic Actions

When triggered, this skill will:

1. Fetch project data from GitHub Project #3 for accurate metrics
2. Analyze current project health metrics
3. Assess milestone balance (features vs. quality ratio)
4. Evaluate strategic priorities
5. Recommend roadmap adjustments if needed
6. Provide data-driven guidance on next steps

Do NOT Use This Skill

• ❌ For implementing individual features (use other implementation skills)
• ❌ For writing code or tests (use implementation skills)
• ❌ For detailed technical design (use UX Design or Architecture skills)
• ✅ Focus on strategic planning and project health guidance

The 5-Checkpoint Strategic Review

This skill uses a systematic 5-checkpoint review process for comprehensive strategic analysis:

CHECKPOINT 1: Project Health Assessment

Objective: Evaluate code quality, technical debt, and testing health

Actions:

1. Analyze code quality metrics (file lengths, god classes, complexity)
2. Review technical debt inventory and age
3. Assess test coverage trends and testing health
4. Evaluate architecture sustainability

Output:

• Health status indicators (🟢🟡🔴) for each dimension
• Key issues and concerns identified
• Recommendations for health improvements

User Confirmation Required: "Agree with assessment? Any concerns?"

---

CHECKPOINT 2: Milestone Balance Analysis

Objective: Ensure sustainable feature/quality ratio

Actions:

1. Calculate current milestone composition (features vs. quality)
2. Apply 70/20/10 rule (70% user value, 20% quality, 10% innovation)
3. Identify imbalances and their risks
4. Recommend adjustments if needed

Output:

• Balance assessment (🟢 Healthy / 🟡 Acceptable / 🔴 Unbalanced)
• Current vs. target allocation breakdown
• Specific recommendations for rebalancing

User Confirmation Required: "Agree with balance assessment? Need adjustments?"

---

CHECKPOINT 3: Priority Recommendations

Objective: Validate issue prioritization is strategic

Actions:

1. Score issues using strategic priority matrix
2. Evaluate user impact, strategic value, technical health, and effort
3. Rank issues by strategic importance
4. Identify quick wins, strategic bets, and deferrals

Output:

• Top-priority issues with strategic reasoning
• Issues to defer with rationale
• Priority scoring breakdown

User Confirmation Required: "Agree with prioritization? Need adjustments?"

---

CHECKPOINT 4: Roadmap Adjustments

Objective: Refine roadmap for optimal strategic outcomes

Actions:

1. Propose specific milestone changes (move in/out issues)
2. Justify each adjustment strategically
3. Assess impact of changes
4. Validate capacity remains reasonable

Output:

• Issues to move out (defer to later)
• Issues to move in (from backlog or create new)
• Strategic rationale for each change
• Before/after balance comparison

User Confirmation Required: "Approve these changes? Need modifications?"

---

CHECKPOINT 5: Action Plan

Objective: Define concrete next steps and success metrics

Actions:

1. Summarize strategic decisions made
2. Define immediate action items
3. Set success metrics to track
4. Schedule next review cadence

Output:

• Concrete action items checklist
• Success metrics defined
• Next review scheduled
• Strategic summary

User Confirmation Required: "Ready to proceed with this plan?"

---

Project Health Assessment Framework

Code Quality Metrics

What to Measure

File Length:

• Average file length across codebase
• Count of files >300 lines (caution threshold)
• Count of files >400 lines (warning threshold)
• Count of files >500 lines (critical threshold)
• Largest file size and location

God Classes:

• Files with multiple responsibilities
• Classes handling >3 distinct concerns
• Screens with business logic mixed with UI

Code Smells:

• Long methods (>50 lines)
• Deep nesting (>4 levels)
• Code duplication instances
• Unclear naming patterns

Health Indicators

🟢 HEALTHY:

• Most files <300 lines
• No files >500 lines
• Regular refactoring (every 2-3 sprints)
• Few code smells flagged in reviews
• Developers report low friction

🟡 WARNING:

• Multiple files 300-400 lines
• 1-2 files >400 lines
• Refactoring overdue (3+ sprints)
• Code smells accumulating
• Some developer friction reported

🔴 CRITICAL:

• Multiple files >400 lines
• Any files >500 lines
• No refactoring in 4+ sprints
• Many code smells in reviews
• Significant developer friction
• Velocity declining

Technical Debt Health

What to Measure

Debt Inventory:

• Total technical debt issues open
• Technical debt as % of total backlog
• Age of oldest tech debt issue
• Average age of tech debt issues

Attention Frequency:

• Sprints since last tech debt work
• % of sprint capacity allocated to debt
• Tech debt issues closed per quarter

Health Indicators

🟢 HEALTHY:

• <20% of backlog is tech debt
• Addressed at least quarterly
• No debt issues >6 months old
• Regular small debt reduction

🟡 WARNING:

• 20-40% of backlog is tech debt
• Addressed occasionally (2-3x per year)
• Some debt issues >6 months old
• Irregular attention

🔴 CRITICAL:

• 40% of backlog is tech debt

• Rarely addressed (<2x per year)
• Many debt issues >1 year old
• Debt accumulating faster than reduction
• Blocking feature development

Testing Health

What to Measure

Test Coverage:

• Overall test coverage percentage
• Coverage trend (increasing/decreasing/stable)
• Coverage gaps in critical paths
• New features without tests

Test Suite Health:

• Total test count
• Test count trend
• Tests broken in last 3 sprints
• Average time to fix broken tests
• Test execution time

Health Indicators

🟢 HEALTHY:

• Test coverage >85%
• Coverage increasing or stable
• Growing test suite
• Tests rarely break (<5% per sprint)
• Quick fixes when tests break (<1 day)
• Fast test execution (<5 min)

🟡 WARNING:

• Test coverage 70-85%
• Coverage stagnant
• Test suite not growing with codebase
• Tests break occasionally (5-15% per sprint)
• Moderate fix time (1-3 days)
• Slow test execution (5-10 min)

🔴 CRITICAL:

• Test coverage <70%
• Coverage declining
• Test suite shrinking or stagnant
• Tests break frequently (>15% per sprint)
• Slow to fix broken tests (>3 days)
• Very slow test execution (>10 min)
• Tests being skipped or disabled

Architecture Health

What to Assess

Service Layer:

• Services properly separated by concern?
• Clear boundaries and responsibilities?
• Easy to test with mocking?
• Following dependency injection patterns?

Data Layer:

• Models clean and focused?
• Database migrations handled well?
• No data integrity issues?
• Queries optimized?

UI Layer:

• Screens focused on UI only?
• Business logic extracted to services?
• Reusable widgets identified?
• State management clear?

Testing Infrastructure:

• Test patterns consistent?
• Mocking infrastructure solid?
• E2E framework working well?
• Tests easy to write?

Health Indicators

🟢 HEALTHY:

• Clean separation of concerns
• Each layer has clear responsibilities
• Dependencies flow correctly
• Easy to add new features
• Architecture enables testing

🟡 WARNING:

• Some boundary blurring
• Occasional responsibility confusion
• Some tight coupling
• New features sometimes awkward
• Testing sometimes difficult

🔴 CRITICAL:

• Poor separation of concerns
• Unclear responsibilities
• Tight coupling throughout
• New features difficult to add
• Testing very difficult
• Architecture impeding progress

---

Milestone Balance Rules

The 70/20/10 Rule

Recommended allocation for sustainable development:

• 70% User Value - Features, enhancements, UX improvements that users see
• 20% Quality Work - Testing, refactoring, tech debt reduction
• 10% Innovation - Exploration, prototypes, architecture experiments

Why This Balance Matters

Too much feature work (>80%):

• Technical debt accumulates
• Code quality degrades
• Velocity eventually slows
• Developer friction increases
• Bugs become more frequent

Too much quality work (>40%):

• Feature delivery slows
• User value delivery delayed
• Momentum lost
• May miss strategic windows

Just right (70/20/10):

• Sustainable velocity maintained
• Code stays healthy
• Features deliver consistently
• Technical debt managed proactively
• Developer satisfaction high

Calculating Balance

For milestone with 14 issues (42 points):

Features: 8 issues, 28 points = 67% ✓
Testing: 3 issues, 8 points = 19% ✓
Refactoring: 2 issues, 4 points = 10%
Tech Debt: 1 issue, 2 points = 5%

Quality Work Total: 24% (19% + 10% + 5%)

Assessment: 🟢 HEALTHY (67% features, 24% quality, 9% other)
Close to 70/30 target, sustainable balance.

Balance Thresholds

🟢 HEALTHY BALANCE:

• 60-75% user value work
• 25-35% quality work
• 0-10% innovation/exploration

🟡 ACCEPTABLE BALANCE:

• 50-60% or 75-80% user value work
• 15-25% or 35-45% quality work
• May be temporarily acceptable if intentional

🔴 UNBALANCED:

• <50% or >80% user value work
• <15% or >45% quality work
• Requires immediate adjustment

---

Priority Scoring Framework

Strategic Priority Matrix

For each issue, evaluate across 4 dimensions:

1. User Impact (1-5 scale)

5 - Critical:

• Blocks core workflows
• Affects all or most users
• Severe pain/frustration
• No workaround available

4 - High:

• Affects major workflows
• Affects many users
• Significant pain/friction
• Poor workaround only

3 - Medium:

• Affects secondary workflows
• Affects some users
• Moderate inconvenience
• Workaround exists

2 - Low:

• Nice-to-have improvement
• Affects few users
• Minor inconvenience
• Easy workaround

1 - Minimal:

• Polish/refinement
• Edge case scenario
• Barely noticeable
• Already adequate

2. Strategic Value (1-5 scale)

5 - Critical:

• Core to product vision
• Enables major future features
• Competitive necessity
• Improves retention significantly

4 - High:

• Aligns strongly with vision
• Enables multiple future features
• Competitive advantage
• Improves retention

3 - Medium:

• Aligns with vision
• Enables some future work
• Competitive parity
• May improve retention

2 - Low:

• Tangentially related to vision
• Limited future enablement
• Nice-to-have competitively
• Minimal retention impact

1 - Minimal:

• Not vision-aligned
• No future enablement
• No competitive impact
• No retention benefit

3. Technical Health (1-5 scale)

5 - Critical:

• Eliminates major tech debt
• Significantly improves architecture
• Enables much better testing
• Unblocks future development

4 - High:

• Reduces meaningful tech debt
• Improves architecture
• Improves testability
• Reduces friction

3 - Medium:

• Maintains current health
• No architecture impact
• Testable but doesn't improve testing
• Neutral impact

2 - Low:

• May introduce minor tech debt
• Minor architecture concern
• Testing becomes slightly harder
• Small friction increase

1 - Minimal:

• Introduces tech debt
• Hurts architecture
• Makes testing difficult
• Significant friction added

4. Effort Score (Inverted - 1-5 scale)

5 - Quick (1-2 points):

• 1-2 story points
• Clear implementation path
• No unknowns
• Quick win

4 - Small (3 points):

• 3 story points
• Straightforward implementation
• Few unknowns
• Reasonable effort

3 - Medium (5 points):

• 5 story points
• Moderate complexity
• Some unknowns
• Fair effort

2 - Large (8 points):

• 8 story points
• Complex implementation
• Several unknowns
• Significant effort

1 - Epic (13+ points):

• 13+ story points
• Very complex
• Many unknowns
• Major undertaking

Priority Calculation

Formula:

Priority Score = (User Impact × 2) + Strategic Value + Technical Health + Effort Score

Maximum Score: 20 (5 × 2 + 5 + 5 + 5)
Minimum Score: 4 (1 × 2 + 1 + 1 + 1)

Why double User Impact?

• User value is primary
• Strategic and technical value support it
• Effort normalized to encourage quick wins

Priority Interpretation

18-20 points: 🔴 CRITICAL PRIORITY

• Do immediately
• High user value + strategic + low effort OR high tech health
• Quick wins or critical fixes
• Example: Critical bug blocking users (5,4,3,5 = 19)

15-17 points: 🟡 HIGH PRIORITY

• Include in next sprint
• Strong user or strategic value
• Reasonable effort
• Example: Requested feature with strategic value (4,4,3,4 = 19)

12-14 points: 🟢 MEDIUM PRIORITY

• Backlog for near-term
• Good value but higher effort OR lower value
• Example: Nice feature but expensive (3,3,2,2 = 13)

8-11 points: ⚪ LOW PRIORITY

• Backlog for later
• Lower value or very high effort
• May defer indefinitely
• Example: Polish item (2,2,2,3 = 11)

4-7 points: ⚫ AVOID/DEFER

• Questionable value proposition
• Very high effort for low return
• Reconsider if worth doing
• Example: Complex feature with minimal impact (2,1,1,1 = 6)

---

Roadmap Adjustment Patterns

When to Recommend Adjustments

Add Refactoring Work

Triggers:

• Last refactoring >2 sprints ago
• Multiple files >400 lines identified
• Code reviews flagging quality issues repeatedly
• Developers reporting "code friction"
• Velocity declining despite consistent team

Recommendation: Add 1-2 refactoring issues (5-8 points total) to next milestone.

Add Testing Work

Triggers:

• Test coverage declining trend
• Tests breaking frequently (>10% per sprint)
• New features shipped without tests
• Edge cases discovered but not tested
• Test suite not growing with codebase

Recommendation: Add testing issues to reach 30% quality allocation.

Defer Features

Triggers:

• Technical debt blocking progress
• Architecture needs strengthening before feature
• Quality metrics declining (🔴 critical status)
• Sprint velocity dropping >20%
• Team experiencing significant friction

Recommendation: Move lower-priority features to next milestone, add quality work.

Accelerate Features

Triggers:

• Urgent beta user feedback
• Competitive pressure (competitor launched similar)
• Strategic window closing (seasonal, market timing)
• Dependency blocking multiple other features

Recommendation: Move high-priority feature earlier, ensure quality work remains >20%.

Adjustment Process

CHECKPOINT 4 Standard Pattern:

1. Identify issues to move out:

   • Lower priority features
   • Nice-to-haves without urgency
   • Polish items that can wait
   • Features with incomplete design

2. Identify issues to move in:

   • Critical refactoring needed
   • Testing gaps identified
   • High-priority issues from backlog
   • Create new quality work if needed

3. Validate capacity:

   • Total points remain similar
   • Balance improves (closer to 70/20/10)
   • No overload on single sprint

4. Justify strategically:

   • Clear rationale for each change
   • Impact analysis provided
   • Long-term benefit explained

---

Technical Debt Sprint Planning

When to Schedule Tech Debt Sprints

Quarterly Pattern (Recommended)

Standard Cadence:

• Every 3-4 feature sprints
• Dedicate 1 sprint to quality
• 80% refactoring/testing, 20% critical bugs only
• Maintains sustainable code health

Immediate Tech Debt Sprint Needed

Critical Indicators:

• 🔴 Multiple files >500 lines
• 🔴 Test coverage <70%
• 🔴 Sprint velocity declining >20%
• 🔴 >40% backlog is tech debt
• 🔴 Tech debt >1 year old present
• 🔴 Developer experiencing significant friction
• 🔴 Architecture blocking new features

When 2+ critical indicators present: Schedule tech debt sprint immediately.

Tech Debt Sprint Structure

Theme: Code Health & Quality Foundation Duration: 5-7 days (1 sprint) Focus: 80% quality work, 20% critical bugs only

Sprint Composition

🔧 Refactoring (50% of sprint):

• Address files >400 lines
• Extract services from god classes
• Eliminate code duplication
• Improve naming and structure

🧪 Testing (30% of sprint):

• Fill coverage gaps
• Add edge case tests
• Improve test infrastructure
• Add E2E tests for critical flows

📚 Documentation (10% of sprint):

• Update architecture diagrams
• Document patterns discovered
• README improvements
• API documentation

🐛 Critical Bugs Only (10% of sprint):

• P0 blockers only
• Defer P1-P2 to next sprint
• Focus on quality work

Success Criteria

Code Quality:

• All files <400 lines (none >500)
• Average file length <300 lines
• Code smells addressed
• Refactoring patterns documented

Testing:

• Test coverage >85%
• All edge case gaps filled
• E2E coverage for critical flows
• Test infrastructure improved

Technical Debt:

• All debt issues >6 months closed
• Remaining debt <20% of backlog
• Clear path for future debt reduction

Developer Experience:

• Developers report reduced friction
• Confidence in making changes increased
• Velocity expected to improve next sprint

---

Architectural Health Assessment

Review Areas

Service Layer Health

Evaluate:

• Are services properly separated by concern?
• Is repository pattern followed consistently?
• Is dependency injection working well?
• Are services easy to mock for testing?
• Do services have clear, focused APIs?

Red Flags:

• Services with multiple responsibilities
• Tight coupling between services
• Direct database access in UI
• Difficult to mock for tests
• Unclear service boundaries

Data Model Health

Evaluate:

• Are models clean and focused?
• Are database migrations handled well?
• Is backward compatibility maintained?
• Are there data integrity issues?
• Are relationships properly modeled?

Red Flags:

• Models with business logic
• Migration failures or manual fixes
• Data integrity violations
• Unclear relationships
• Primitive obsession

UI Layer Health

Evaluate:

• Are screens <400 lines?
• Are widgets reusable?
• Is state management clear?
• Is business logic extracted?
• Is testing straightforward?

Red Flags:

• Screens >500 lines
• No widget reuse
• Unclear state flow
• Business logic in UI
• Difficult to test

Testing Infrastructure Health

Evaluate:

• Are test patterns consistent?
• Is mocking infrastructure solid?
• Is E2E framework working well?
• Are tests easy to write?
• Do tests run fast?

Red Flags:

• Inconsistent test patterns
• Difficult mocking
• E2E tests flaky
• Tests hard to write
• Slow test execution

Long-Term Architectural Risks

Assess for each major milestone:

Current Milestone Risks:

• What architectural limitations exist now?
• What technical debt might block features?
• What refactoring is needed before proceeding?

Next Milestone Risks:

• What architectural changes needed?
• What assumptions might break?
• What preparation needed now?

Future Milestone Risks (2-3 ahead):

• What major architectural shifts needed?
• What groundwork to lay now?
• What patterns to establish early?

---

Review Cadence Recommendations

Monthly Strategic Review

When: First week of each month Duration: 30-45 minutes Scope: Full 5-checkpoint review

Covers:

• Project health assessment
• Next 2-3 milestones balance check
• Priority validation
• Roadmap adjustments if needed
• Action plan for month

Deliverable: Strategic review document

Sprint Review (Optional)

When: End of each sprint Duration: 10-15 minutes Scope: Quick health check

Covers:

• Milestone balance quick check
• Priority confirmation
• Any urgent adjustments

Deliverable: Brief status update

Quarterly Planning

When: Start of each quarter Duration: 1-2 hours Scope: Deep strategic review

Covers:

• Long-term vision alignment
• Major architectural decisions
• Multi-milestone roadmap
• Tech debt sprint planning
• Resource allocation

Deliverable: Quarterly strategic plan

---

Integration with Other Skills

Works well with:

Skill	Integration Point
Issue Roadmap	Validates roadmap balance and priorities before detailed planning
Sprint Planning	Ensures sprints are strategically aligned
Refactoring	Identifies when refactoring work is needed
Testing Implementation	Ensures testing gets adequate time allocation
UX Design	Validates feature priorities align with user value
Database Migration	Considers architectural evolution
Code Review	Validates code quality trends inform strategy

Workflow Position:

Product Strategy → Issue Roadmap → Sprint Planning → Implementation → Review → Product Strategy
     ↓                                                                              ↑
  Validates                                                                   Informs next
  priorities                                                                    cycle

---

Key Principles

1. Never just agree - Provide strategic analysis, challenge when needed
2. Data-driven - Use metrics, not opinions
3. Balance is key - Features AND quality, not features OR quality
4. Think long-term - Beyond current sprint and milestone
5. Enforce quality time - Protect 20-30% for quality work
6. Prevent debt accumulation - Proactive, not reactive
7. Strategic over tactical - "Why" and "when" matter more than "how"
8. User value primary - But not at expense of sustainability

---

Success Metrics

This skill is successful when:

• ✓ Roadmaps maintain 60-75% user value, 25-35% quality balance
• ✓ Technical debt stays <20% of backlog
• ✓ Tech debt sprints scheduled quarterly
• ✓ No files >500 lines accumulate
• ✓ Test coverage remains >85%
• ✓ Velocity stable or improving over time
• ✓ Priorities validated strategically (not just user requests)
• ✓ Architectural risks identified early
• ✓ Quality work gets protected time
• ✓ Project health stays 🟢 or 🟡 (never 🔴 for long)

---

The "Wide Picture" Promise

This skill ensures you never lose sight of:

• 🎯 Strategic direction - Are we building the right things?
• 🏗️ Code health - Is the codebase sustainable long-term?
• ⚖️ Balance - Are we doing enough quality work?
• 🔮 Long-term vision - What risks are we creating for future milestones?
• 📊 Metrics - How healthy is the project objectively?
• 🚀 Velocity - Are we maintaining sustainable pace?

You're not just building features - you're building a sustainable, healthy product.