stacked
Decompose LARGE, complex, or risky changes into a stack of small, dependent, independently reviewable units. Use only when the change is genuinely big: multiple architectural layers with functionally distinct concerns (models + storage + logic + API + UI), or a diff too large to review as one unit. Trigger on "stacked" / "stacked PRs" / "stack this" / how to break down a large change — or when a "build X" / "refactor W" request is clearly multi-layer and large. Do NOT use for small or moderate changes: bug fixes, tweaks, config, single-file or single-layer changes belong on ONE branch as ONE change — a stack of tiny branches adds overhead without value.
- License 许可
- MIT
- 所属仓库
- auth-02/hub
- 最近更新
- 2026-08-12
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- stacked
- description
- Decompose LARGE, complex, or risky changes into a stack of small, dependent, independently reviewable units. Use only when the change is genuinely big: multiple architectural layers with functionally distinct concerns (models + storage + logic + API + UI), or a diff too large to review as one unit. Trigger on "stacked" / "stacked PRs" / "stack this" / how to break down a large change — or when a "build X" / "refactor W" request is clearly multi-layer and large. Do NOT use for small or moderate changes: bug fixes, tweaks, config, single-file or single-layer changes belong on ONE branch as ONE change — a stack of tiny branches adds overhead without value.
02 资源文件 1
- 参考文档examples/notifications-system.md2.0 KB
03 SKILL.md 正文
Stacked
Decompose work into a stack of small, dependent, reviewable changes. Each change has a single responsibility and builds on the one below it.
When to Use
Stack only when all of these hold:
- The change is large — too big to review comfortably as a single unit
- It spans multiple architectural layers with functionally distinct concerns
- Each layer would carry substantial, self-contained work worth its own review
When NOT to Use
Default to a single branch, single change for:
- Bug fixes, tweaks, styling adjustments, config or copy changes
- Single-file or single-layer changes, however "multi-step" the edit feels
- Small features a reviewer can absorb in one sitting
- Related small changes — batch them into one coherent change rather than one branch each
A stack of tiny branches is worse than one clear change: it multiplies review, CI, and merge overhead without improving reviewability. The size of the change decides, not the number of steps it took to write.
Core Principle
Prefer a stack of small changes over one massive change — and prefer one plain change over an unnecessary stack. Stacking is a tool for taming size, not a default workflow.
Small Change ← top (depends on everything below)
↑
Small Change
↑
Small Change
↑
Small Change ← bottom (no dependencies)
Implement from the bottom up. Review from the bottom up.
Decomposition Strategy
Before writing any code:
- Understand the complete scope
- Identify architectural boundaries
- Separate concerns
- Build a proposed stack
- Validate each layer has a single responsibility
Think in terms of:
- Data structures — types, models, schemas
- Persistence — storage, migrations, indexes
- Domain logic — business rules, transformations
- Tools / Services — utilities, clients, adapters
- Workflows — orchestration, pipelines, agents
- API — interfaces, contracts, endpoints
- UI — presentation, interaction
Not every feature requires every layer.
Preferred Layering Order
Types / Models
↓
Persistence
↓
Domain Logic
↓
Tools / Services
↓
Workflows
↓
API
↓
UI
Higher layers depend on lower layers. Lower layers must not depend on higher layers.
Naming
Name each change by capability and responsibility — not sequence.
Good:
search/indexing
search/retrieval
search/ranking
search/api
doc-parser/core
doc-parser/chunking
doc-parser/indexing
doc-parser/workflow
chat/session-model
chat/history-store
chat/context-builder
chat/agent
Avoid:
part-1
part-2
final
misc
changes
Names should explain what a change does without requiring additional context.
Reviewability Rule
Each change should answer a single question:
Does [this specific thing] look correct?
Examples:
- "Does the indexing model look correct?"
- "Does the retrieval implementation look correct?"
- "Does the workflow orchestration look correct?"
If a reviewer must answer multiple unrelated questions, the change is too large. Split it.
Agent Behavior
- Plan the full stack first — propose it before writing any code
- Explain the proposed stack — show names, dependencies, and responsibilities
- Implement bottom-up — start with the lowest-dependency layer
- Keep responsibilities isolated — no mixing of architectural layers within a change
- Avoid unrelated refactors — scope each change tightly
- Prefer incremental progress — don't bundle work to seem efficient
- Write into the manifest — when a manifest exists for this task (
tasks/<slug>/manifest.md), write the stack into its## Stacksection rather than presenting it only in chat. The manifest is the canonical record; chat is ephemeral. Update layerStatuscells as PRs open and merge.
When uncertain whether the change is big enough to warrant a stack: don't stack it — ship it as one change. Only once you're inside a genuinely large stack and uncertain whether a layer is doing two jobs: split that layer.
Sizing floor: never create a layer that a reviewer would read in under a couple of minutes and think "why is this its own PR?" Merge such fragments into the adjacent layer they belong to.
Output Format
When proposing a stack, present it clearly:
feature-name/layer-one ← implement first
↑
feature-name/layer-two
↑
feature-name/layer-three
↑
feature-name/layer-four ← implement last
For each layer, briefly state:
- What it does (one sentence)
- What it depends on (prior layers, if any)
- Why it's its own change (the single reviewable question)
Example
User request: Build a document intelligence pipeline that can parse, chunk, index, and search documents.
Proposed stack:
doc-intelligence/models ← types and schemas
↑
doc-intelligence/parser ← raw document ingestion
↑
doc-intelligence/chunking ← splitting and segmentation logic
↑
doc-intelligence/indexing ← storage and index construction
↑
doc-intelligence/search ← retrieval and ranking
↑
doc-intelligence/workflow ← end-to-end orchestration
Each layer has one job. Each layer can be reviewed independently. The story is clear from bottom to top.
Success Criteria
A stack is successful when:
- Each change has one responsibility
- Dependencies are obvious from the names and order
- Changes are independently reviewable
- The implementation story is clear from bottom to top
- Testing can happen incrementally
- Merging can happen incrementally
- A reviewer can understand the full stack without confusion
Worked example (in examples/)
examples/notifications-system.md is a worked example showing how a complex feature — an in-app notifications system spanning schema, storage, delivery, API, and UI — decomposes into one tight bottom-up stack. Only the Stack section is shown: each layer's responsibility, its dependency on the layer below, the single reviewable question it answers, and its status. Note how even a large, multi-concern feature reduces to a short ladder where each layer is independently reviewable and nothing above can be built until the layer below it is tested.
04 同仓库更多 Skills
manifest
Use when starting a non-trivial feature, migration, refactor, or multi-step task in ANY repo. Creates and continuously maintains a living markdown manifest at `<repo-root>/tasks/<slug>/manifest.md` (inside the repo being worked on — NEVER the skill dir or ~/) capturing the problem, decisions, exploration results, plan, open questions, test + rollout plans, and final review. Trigger on "build X", "add X", "migrate X", "refactor X", tasks needing 3+ steps, or whenever a plan-before-code loop would help. NOT for single-line fixes, obvious bugs, or one-shot questions.
kagaz
Kagaz (कागज़) — a personal design system for all frontend and document work — editorial-technical-archival, serif display + mono metadata on warm paper tones with a single rust accent. Use for ANY frontend, UI, web page, landing page, dashboard, artifact, component, mockup, poster, slide deck, report, or PDF/document design, for HTML→PDF conversion, and for any "make this look good" / "style this" / "make slides" / "turn this into a PDF" request — even when no design preference is mentioned. Overrides generic AI defaults (Inter-on-white, purple gradients, cool grays). Ships an HTML-to-PDF converter with visual QA and on-brand SVG charts.
dak
暂无简介
change-log
Map a task's changes as an editable draw that renders an interactive change-map on Save — nodes are functional CHANGES (a capability that moved), arrows are dependencies, and clicking a change deep-dives into its file / function / test detail in a side inspector. Use when someone asks "what changed", "map this change", "diagram this PR/branch", "show how the changes connect", or as the closing step of a task once code has landed. Reads the diff + the task's manifest (the *why*) + Hub's MCP task context, then writes ONE `.excalidraw` into `tasks/<slug>/change-log/`; the user edits it and Saving renders the sibling HTML. The agent does the reading — Hub has no model. `/change-log <task-slug> [--since <ref>] [--doc]`.
auth
暂无简介
rate_limiting
暂无简介