[Issue #31] Add guidance for vertical vs horizontal slicing #55

HugoNijhuis · 2026-01-09T12:22:09Z

HugoNijhuis commented

2026-01-09 12:22:09 +00:00

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

## 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

HugoNijhuis added 1 commit 2026-01-09 12:22:09 +00:00

Add vertical vs horizontal slicing guidance 65a107c2eb

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>

HugoNijhuis commented

2026-01-09 12:23:11 +00:00

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.

## 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.

HugoNijhuis merged commit 65a107c2eb into main

2026-01-09 12:23:17 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: flowmade-one/architecture#55