Skip to content
Skills Library
Programming · Analysis

shape

/shape

Use when a feature has settled intent and codebase facts but multiple viable implementation approaches remain.

Repository
qrspi-x ↗
Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when a feature has settled intent and codebase facts but multiple viable implementation approaches remain.

Original author description

Use when a feature has settled intent and codebase facts but multiple viable implementation approaches remain.

How it works

  1. Core Philosophy
  2. The helper
  3. Task
  4. After the Agent Returns
Original SKILL.md headings · 65 lines, 646 words
SKILL.md preview
---
name: shape
description: 'Use when a feature has settled intent and codebase facts but multiple viable implementation approaches remain.'
when_to_use: 'Use optionally after Query ↔ Research and before Spec when the solution direction is not obvious. Skip it and use `qrspi-x:spec` when one reasonable approach is clear; use `qrspi-x:query` or `qrspi-x:research` when intent or codebase facts are still unclear.'
disable-model-invocation: false
compatibility: Node 22+
---

# QRSPI Shape

## Core Philosophy
- Resolve meaningful implementation alternatives before freezing the behavioral contract

This skill is part of the QRSPI workflow and is normally invoked by `qrspi-x:workflow`. It may also be invoked directly.

Runtime contract: read `../workflow/references/runtime.md` before dispatch. It defines the fresh-context, capability, fallback, and on-disk evidence requirements; this skill adds only Shape-specific inputs and output.

## The helper
Helper installation, recovery, and artifact-only fallback are defined by `qrspi-x:workflow`. Shape has no `qrspi-x` state of its own; when the helper is available it's used only for backup naming on a rerun, per the Task steps below. `status`'s optional `current.step` convenience reads `approach.md`'s `## Decision` section, but never gates on it. If it exits 127, continue this interactive step without it. Never edit any helper state manually.

## Task
Explore and compare candidate implementation approaches for a settled feature. Shape is an optional, human-gated definition step: it decides how the feature should be approached, but it does not write product code, define the behavioral spec, or create an implementation plan.

The shaper uses all available pre-definition context:
- `./qrspi/<feature>/request.md` — the settled intent
- `./qrspi/<feature>/background.md` — optional human context and prior art
- `./qrspi/<feature>/queries.md` — the questions that framed research
- `./qrspi/<feature>/research.md` — codebase facts and constraints

1. Verify that `request.md`, `queries.md`, and `research.md` exist. If any is missing, stop and direct the caller to Init, Query, or Research. `background.md` is optional.
2. If `research.md` has a non-empty `## New Questions`, stop and return to Query before shaping; do not design around unresolved facts.
3. If `approach.md` exists, retain its complete contents and move it to `./qrspi/<feature>/backups/approach-<n>.md`, where `n` is one greater than the highest `n` already present for the `approach` stem, starting at 1 (if the helper is available, `qrspi-x next-file approach --feature <feature> --project <path>` returns this path directly — same result, no need to list `backups/` and compute `n` by hand). Never rename, rotate, or overwrite an existing backup — writing one is always a pure addition. Create `backups/` only when there is something to put in it.
4. Before spawning, prefer the declared agent when the runtime supports named agents:
   - If `qrspi-x:shaper` is registered, spawn it directly so the runtime can apply its declared settings.
   - Otherwise, read `../../agents/shaper.md`, resolved relative to this `SKILL.md`, and spawn a general-purpose subagent with its full contents as the role instructions.
5. Pass the feature name so the agent can locate the four artifacts, noting that `background.md` may be absent. The agent may read the codebase to validate candidate approaches, but it must write only `./qrspi/<feature>/approach.md`.
6. If `approach.md` already exists, preserve its prior decision and rationale while refining the alternatives; never silently replace a recorded decision.

The approach artifact should make the choice reviewable:

```markdown
# QRSPI Approach: <feature>

## Context
...

## Constraints and Facts
...

## Candidate Approaches
### Option A: ...
...

## Recommendation
...

## Decision
None.

## Open Questions
...
```

## After the Agent Returns

1. Read the agent's report and inspect `approach.md` for candidate approaches, tradeoffs, and a recommendation.
2. If the comparison exposes missing facts, stop and return to Query/Research rather than guessing.
3. Stop for human review. The human may approve the recommendation, select another option, or edit `approach.md`; replace `None.` under `## Decision` with the selected approach and rationale before proceeding to Spec. The shaping pass is complete when `approach.md` is written, but the human decision is a separate gate.
4. Leave `None.` in place under `## Decision` until the human decides — any other text, including a comment, reads as a decision. `status`'s optional `current.step` convenience reads this same section to tell `shape` from `spec`, but never gates on it; the Shape gate itself stays this skill's own read of `approach.md`.

Do not write `spec.md` or plan files. If the approach is obvious, skip this step entirely and use `qrspi-x:spec`.

Versions

RepositoryScoreLicence
This page · ebullient/qrspi-x100Apache-2.0
biliboss/skills100MIT
gmdkaio/kstack100MIT
YnotnaUK/ai-skills100MPL-2.0
jamesm-dev/payday-dev100MIT
nyelonong/galdr100MIT
thecraighewitt/skills100MIT
tiago-peixoto/claude-shapeup95MIT
educlopez/ui-craft92MIT

Database snapshot: 13.11.2026 · package version 6ec106caa9a9 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100research
    Investigate a codebase, compare tools or approaches, verify current external or library facts, and research failures before making a substantive technical recommendation. Use for sufficiency and gap reviews; ordinary edits with settled requirements do not need a research stage.
  • 90brainstorming
    Draws out what the user wants and why, compares two or three approaches grounded in the code, grills open decisions in rounds, and gets a design doc approved before any code is written. Use before building or changing anything whose intent is not settled: a new feature,…
  • 100write-plan
    Write an implementation plan. Use when the behavior is settled and how to build or fix it is open — a pinned cause, settled spec, hunt finding, or review comment. Not for deciding the behavior (write-specs) or multi-session work (frontier).
  • 90compare-options
    Compare multiple approaches, libraries, or patterns. Searches codebase for existing usage, checks memory for past experiences, creates comparison matrix. Use when deciding between approaches before implementation.
  • 90design
    Brainstorm design options for a feature and document the result. Use when the user asks to design a new feature or a major change to an existing one, compare implementation approaches, or create/update a design doc in docs/design/ or experiments/<username>/<project>/docs.
  • 100capture-decisions
    Capture settled durable decisions into existing owning repo memory, or ask where to record them before creating a destination. Use after discussion, research, specs, reviews, or implementation when the user asks to record decisions, durable memory, glossary terms, ADR-worthy…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.