---
name: gstack-plan
description: "Use before building a feature: challenge the scope, then review architecture, code quality, tests and performance, and end with a plan to build. (gstack)"
title: gstack-plan
canonical_url: https://skilld.dev/gh/garrytan/gstack/gstack-plan
last_updated: 2026-11-12T07:04:31.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install garrytan/gstack/gstack-plan`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/gstack-plan`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/garrytan/gstack/gstack-plan) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/gstack-plan`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/gstack-plan --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/gstack-plan --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

<!-- Generated by scripts/gen-qm-edition.ts from hosts/qm.ts and plan-eng-review/SKILL.md.tmpl, plan-eng-review/sections/review-sections.md.tmpl. Do not edit. -->

# Plan a feature: scope first, then the engineering review

Review a plan, not code: do not build the feature. If the user has not given you the plan or feature description, ask for it and stop.

**Start here.** In the repository (`cd` into it first: the shell starts in the workspace root), run with `execute` to see what already exists:

```sh
git log --oneline -10
ls
```

Then read the files the plan touches. Work through Scope Challenge, then Sections 1-4 in order; for each finding give severity, a recommendation and the alternative. Ask about decisions that change scope in one message and stop until the user answers. Finish with the revised plan: what to build, in order, the files it touches, the tests that prove it, and what is NOT in scope.

## My engineering preferences (use these to guide your recommendations):
* **Shared code:** require common behavior and improved reliability or net savings; similar-looking code alone is insufficient.
* **Tests:** every behavior tested; no test without a regression it would catch.
* **Enough engineering:** avoid fragility and premature abstraction/complexity.
* **Edge cases:** thorough handling over speed.
* **Explicit over clever.**
* **Right-sized diff:** smallest clear change; rewrite a broken foundation when necessary.
* **Data model:** storage follows the data's queries, integrity rules and update boundaries, not file count: fields queried, constrained or updated on their own get explicit columns or tables; JSON suits a document read and written whole.

## A. Assess the target

Complete these checks before proposing scope changes. Do not write findings into the plan yet.

- **What already solves each sub-problem?** Inspect helpers, libraries, callers and reusable outputs: behavior and dependency/deployment boundaries. Cite authored sources; label proposed callers with their motivating plan requirement and assumptions.
- **What minimum changes achieve the goal?** Flag work deferrable without blocking it; challenge scope creep.
- **Complexity check:** Count the selected work, not files read only as evidence:
  for a plan, its proposed changed files and new classes/services; for a diff,
  changed files and classes/services introduced by that diff; for a file/directory,
  files in that selected scope and any explicitly proposed new classes/services.
  Count each once, label estimates, and seek fewer moving parts. At 8+ files or 2+ new classes or services, propose a smaller arrangement and ask before changing scope.

- **Distribution check:** For new artifacts, verify build/publish CI/CD, target
   OS/architectures and download/install channels. Put deferrals in "NOT in scope".

## Review Sections (after scope is agreed)

Evaluate Architecture → Code Quality → Tests → Performance. Never condense,
abbreviate or skip a section, including strategy/spec/infra plans.

### 1. Architecture review
Evaluate:
* System/component boundaries, dependencies and coupling.
* Data flow, bottlenecks, scaling and single points of failure.
* Security: auth, data access and API boundaries.
* Key flows needing ASCII diagrams in plans/code.
* One realistic production failure per new path/integration; does the plan handle it?
* **Distribution architecture:** New artifacts' build, publish and update paths; included or deferred CI/CD.

<!-- "Design it twice" and the red flags derive from pstack's architect skill (Lauren Tan, MIT), rewritten for gstack. See NOTICE.md. -->
### Two shapes before one (design-twice)

Run this only when the plan introduces a new module, service, package or
boundary: a public surface other code calls; otherwise say so in one line.

**Ask for the second shape.** A plan with one design usually took the first
shape that compiled in the author's head. Before judging it, require a second
shape that is structurally different: another owner for the state, another
split of responsibilities, another place for the boundary. A point fix inside
the first shape is not a second candidate. When the plan has none, sketch one
in five lines (types and signatures, bodies `not implemented`) and record it
as the alternative. Compare the candidates on interface depth: how much
behavior and policy each hides behind how small a public surface, and prefer
the one that hides more behind less. A deep module is not a deep call chain:
the chain scatters the understanding across layers, the module concentrates
it behind one interface.

**The eight red flags.** Screen the chosen shape before Section 1 closes.
Assume the next contributor is an agent that sees only the files it opened,
copies the nearest example and takes the shortest path that compiles; prefer
the design where a change that looks right from one file is right for the
whole repo. A flag is a finding with a file or symbol and a reason to revise
the shape, not a comment asking for care.

1. **Shallow module.** A large interface over little hidden complexity:
   several calls per operation, options that expose internal stages.
2. **Information leakage.** One decision (a representation, a policy, a wire
   or storage detail) lives in more than one module. Re-exported transport
   types are leakage; parse external data into domain types at the boundary.
3. **Temporal decomposition.** Modules split by execution order (load,
   validate, transform, save) instead of by the knowledge they own.
4. **Pass-through method.** A function that forwards the same arguments to
   another with the same shape; remove it or move the responsibility.
5. **Split ownership.** Two modules write the same state or each keep a copy;
   an agent editing one cannot see the other. One owner per piece of state.
6. **Two ways to do one task.** An agent copies whichever it meets first.
   Keep one; move the callers and delete the rest in the same change.
7. **Importable internals.** The shortest path that compiles imports them and
   they become interface. Make an outside import fail the build.
8. **Hand-synced list.** The same items in two places; an agent that sees one
   list edits one. Derive the second, or fail the build when they disagree.

Record under Architecture: both shapes, the pick, the depth argument for it,
and each flag with its fix.

### 2. Code quality review
Evaluate:
* Organization and module structure.
* Shared-code opportunities in the target and related callers. No standalone history/PR sweep or quotas. Check proposed caller assumptions against existing interfaces.
* Explicitly flag error handling gaps and missing edge cases.
* Technical debt, fragility and needless complexity per engineering preferences.
* Accuracy of touched files' ASCII diagrams.

### 3. Test review

For shared-code changes, audit existing/missing shared-contract tests (behavior,
errors, side effects, boundaries) and each migrated caller's integration/differences.
Rejected extractions still need coverage for real duplicated-code defects.

For every new codepath, branch and error path in the plan, name the test that proves it (unit, integration or end-to-end) and the regression it would catch. Missing tests become plan items.

### 4. Performance review
Evaluate:
* N+1 queries and database access patterns.
* Memory usage.
* Caching opportunities.
* Slow or complex paths.

On per-request or looped paths, check queries in loops, unbounded
queries or caches, missing indexes, whole-file loads and blocking calls without
timeouts. Give each finding's scale (rows, requests/s, bytes) or mark it
unknown; never invent benchmarks.
