## Summary
Adds guidance to prefer vertical slices (user-visible value) over horizontal slices (technical layers) when planning and writing issues.
## Changes
**roadmap-planning skill:**
- New "Vertical vs Horizontal Slices" section
- Demo test: "Can a user demo/test this independently?"
- Good vs bad examples table
- When horizontal slices are acceptable
**issue-writing skill:**
- New "Vertical Slices" section
- Demo test guidance
- Good vs bad issue titles table
- User-focused issue framing examples
Closes #31
Adds guidance to prefer vertical slices (user-visible value) over
horizontal slices (technical layers) when planning and writing issues.
roadmap-planning skill:
- New "Vertical vs Horizontal Slices" section
- Demo test: "Can a user demo/test this independently?"
- Good vs bad examples table
- When horizontal slices are acceptable
issue-writing skill:
- New "Vertical Slices" section
- Demo test guidance
- Good vs bad issue titles table
- User-focused issue framing examples
Closes#31
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This is an automated review generated by the code-reviewer agent.
Summary
The PR adds valuable guidance on preferring vertical slices over horizontal slices when planning and writing issues. The content is clear, well-structured, and consistent between both skills. The examples are concrete and practical.
Findings
Code Quality
The documentation structure is clean and well-organized:
Both files follow consistent formatting and structure
The "Vertical Slices" sections are appropriately placed (early in issue-writing, after planning process in roadmap-planning)
Examples progress from simple comparisons to more complex scenarios
Markdown formatting is correct and consistent
Content Clarity
Strengths:
The "Demo Test" is a brilliant, simple heuristic that makes the concept actionable
Good/Bad comparison tables provide immediate visual understanding
The caveat section "When Horizontal Slices Are Acceptable" prevents dogmatic application
Examples span different domains (diagrams, orders, auth) showing broad applicability
Minor observation:
roadmap-planning/SKILL.md line 80-87 contains a "By Layer" breakdown example that directly contradicts the vertical slicing guidance just introduced. This isn't necessarily wrong (as it's showing different planning approaches), but the juxtaposition is jarring. Consider adding a note like "Note: The following sections show alternative breakdown strategies - prefer vertical slices unless horizontal is justified."
Consistency Between Files
Excellent consistency:
Both use the same "Demo Test" framing
Examples in both files use similar problem domains
Tone and style match across both skills
The roadmap-planning version provides more depth (when horizontal is acceptable), while issue-writing focuses on practical title writing
Missing Edge Cases
Minor gaps worth considering:
Transitional state: What if a feature genuinely requires foundation work before any vertical slice is possible? The "When Horizontal Slices Are Acceptable" section addresses this but could add an example
Backend-only features: The guidance implicitly assumes user-facing features. What about backend improvements (performance, monitoring, refactoring)? These can still be framed as user value but this nuance isn't addressed
Mixed slicing: Sometimes a feature needs one horizontal slice followed by several vertical ones. An example of this pattern would be helpful
Writing Quality
Excellent overall:
Clear, direct language
Active voice throughout
Good use of formatting (bold, tables, code blocks) for scannability
The contrast between "Bad: Technical task" and "Good: User capability" examples is particularly effective
Verdict
LGTM
This is high-quality documentation that addresses a real pain point in issue planning. The guidance is practical, the examples are concrete, and the "Demo Test" heuristic is memorable and actionable. The slight tension with the "By Layer" example in roadmap-planning is minor and doesn't block merge.
The PR successfully closes#31 and will improve how issues are structured and planned across the organization.
## AI Code Review
> This is an automated review generated by the code-reviewer agent.
### Summary
The PR adds valuable guidance on preferring vertical slices over horizontal slices when planning and writing issues. The content is clear, well-structured, and consistent between both skills. The examples are concrete and practical.
### Findings
#### Code Quality
The documentation structure is clean and well-organized:
- Both files follow consistent formatting and structure
- The "Vertical Slices" sections are appropriately placed (early in issue-writing, after planning process in roadmap-planning)
- Examples progress from simple comparisons to more complex scenarios
- Markdown formatting is correct and consistent
#### Content Clarity
**Strengths:**
- The "Demo Test" is a brilliant, simple heuristic that makes the concept actionable
- Good/Bad comparison tables provide immediate visual understanding
- The caveat section "When Horizontal Slices Are Acceptable" prevents dogmatic application
- Examples span different domains (diagrams, orders, auth) showing broad applicability
**Minor observation:**
- roadmap-planning/SKILL.md line 80-87 contains a "By Layer" breakdown example that directly contradicts the vertical slicing guidance just introduced. This isn't necessarily wrong (as it's showing different planning approaches), but the juxtaposition is jarring. Consider adding a note like "Note: The following sections show alternative breakdown strategies - prefer vertical slices unless horizontal is justified."
#### Consistency Between Files
Excellent consistency:
- Both use the same "Demo Test" framing
- Examples in both files use similar problem domains
- Tone and style match across both skills
- The roadmap-planning version provides more depth (when horizontal is acceptable), while issue-writing focuses on practical title writing
#### Missing Edge Cases
**Minor gaps worth considering:**
- **Transitional state**: What if a feature genuinely requires foundation work before any vertical slice is possible? The "When Horizontal Slices Are Acceptable" section addresses this but could add an example
- **Backend-only features**: The guidance implicitly assumes user-facing features. What about backend improvements (performance, monitoring, refactoring)? These can still be framed as user value but this nuance isn't addressed
- **Mixed slicing**: Sometimes a feature needs one horizontal slice followed by several vertical ones. An example of this pattern would be helpful
#### Writing Quality
Excellent overall:
- Clear, direct language
- Active voice throughout
- Good use of formatting (bold, tables, code blocks) for scannability
- The contrast between "Bad: Technical task" and "Good: User capability" examples is particularly effective
### Verdict
**LGTM**
This is high-quality documentation that addresses a real pain point in issue planning. The guidance is practical, the examples are concrete, and the "Demo Test" heuristic is memorable and actionable. The slight tension with the "By Layer" example in roadmap-planning is minor and doesn't block merge.
The PR successfully closes #31 and will improve how issues are structured and planned across the organization.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Summary
Adds guidance to prefer vertical slices (user-visible value) over horizontal slices (technical layers) when planning and writing issues.
Changes
roadmap-planning skill:
issue-writing skill:
Closes #31
AI Code Review
Summary
The PR adds valuable guidance on preferring vertical slices over horizontal slices when planning and writing issues. The content is clear, well-structured, and consistent between both skills. The examples are concrete and practical.
Findings
Code Quality
The documentation structure is clean and well-organized:
Content Clarity
Strengths:
Minor observation:
Consistency Between Files
Excellent consistency:
Missing Edge Cases
Minor gaps worth considering:
Writing Quality
Excellent overall:
Verdict
LGTM
This is high-quality documentation that addresses a real pain point in issue planning. The guidance is practical, the examples are concrete, and the "Demo Test" heuristic is memorable and actionable. The slight tension with the "By Layer" example in roadmap-planning is minor and doesn't block merge.
The PR successfully closes #31 and will improve how issues are structured and planned across the organization.