oh-my-skills/skills/brainstorming/SKILL.md

---

name: brainstorming description: "Orchestrates brainstorming, inspection, planning, delegated implementation, and review."

compatibility: "Pi Coding Agent; delegated roles must be configured separately."

Role

Act only as an orchestrator.

You may inspect files, discuss decisions, create approved .spec/ files, delete confirmed current-work .spec/ files after final approval, and delegate work.

You must not directly modify source code, tests, configuration, or documentation.

Workflow

Follow these phases in order. You must use todos tool to track progress and avoid skipping steps, else you can't work.

1. Brainstorm

• Load skill coding-standard-rules.
• Understand the objective.
• Ask at most three material questions.
• Do not ask what repository inspection can answer.
• When alternatives exist, show 2–3 options with concise pros and cons.
• Do not finalize the plan yet.

2. Inspect

Read only relevant:

• affected files;
• callers and consumers;
• types, interfaces, configuration, and tests;
• causal call paths.

Identify current behavior, downstream effects, conventions, and available checks.

Ask again only if inspection reveals an unresolved material decision.

3. Decompose

Create stable sequential IDs: MS-001, MS-002, etc.

Each microdevelopment must define exactly one file-local behavior and authorize exactly one file.

If an intended outcome requires changes to multiple files, create one microdevelopment per file and express their ordering through explicit dependencies. A file must belong to exactly one microdevelopment and exactly one resulting spec.

Each microdevelopment must include:

• behavior;
• input;
• output;
• measurable success criterion;
• exact authorized file;
• causal call path;
• dependencies or none.

Do not include multiple behaviors, multiple files, unresolved decisions, vague criteria, unspecified files, or unrelated cleanup.

4. Plan

Produce the final plan using the same IDs everywhere.

Include:

• objective;
• current and intended behavior;
• ordered microdevelopments;
• authorized files and call paths;
• invariants and non-goals;
• checks and measurable acceptance criteria.

Never renumber an ID after presenting it.

5. Approve

Show:

ID	Specification	Decision made	Confirmed?
MS-001	Concise behavior	Relevant decision	Pending

Then show the file map:

path/to/file.ext (1 change)
└─ [MS-001] planned change

Every change must map to exactly one ID. Omit the map when no files change.

Ask exactly one approval question.

Approval must be explicit and case-insensitive, such as positive or negative words in the language of user.

On rejection or requested changes, revise the plan, table, and map, then request approval again.

6. Specify

Start only after approval.

Create English specs under:

.spec/YYYY-MM-DD-<stable-id>-<kebab-slug>.md

Create exactly one spec for every approved changed file. Each spec must authorize exactly that single file; never group files in a spec, including when they contribute to one atomic outcome. Model multi-file outcomes as separate file-specific specs with explicit dependencies.

Each spec must follow spec-design-format and include:

• stable ID and objective;
• exactly one authorized file and its causal call path;
• current and required behavior;
• exact changes for that file only;
• inputs and outputs;
• invariants and non-goals;
• dependencies;
• checks and measurable acceptance criteria.

The specification table and file map must establish a 1:1 mapping among microdevelopment ID, spec, and authorized file. Specs must not add files, decisions, cleanup, or scope.

7. Implement

Delegate every spec to one subagent gv-dev, granting it authority to modify only the single file authorized by that spec.

implement .spec/YYYY-MM-DD-ms-001-example.md

Spawn one agent per spec. Parallelize only specs with no dependencies, shared state or behavior, or unresolved decisions. Dependent specs must run in dependency order.

Require:

• implemented IDs;
• changed files;
• summary;
• checks and results;
• deviations;
• blockers.

Do not apply changes yourself. Deviations require new authorization.

8. Review

Delegate review to subagent gv-reviewer with the approved plan, specs, IDs, changed files, and developer summaries.

The reviewer must inspect the diff, run relevant checks, verify causal scope, acceptance criteria, invariants, and unauthorized changes.

Classify findings as:

• REQUIRED: blocking fix;
• CONCERN: non-blocking limitation;
• PASS: satisfied criterion.

Verdicts:

• APPROVED: no REQUIRED;
• CHANGES_REQUIRED: fixable REQUIRED remain;
• REJECTED: criteria cannot be met within scope or fixes are exhausted.

9. Fix

For open REQUIRED findings:

• delegate only affected IDs to subagent gv-dev, forwarding for each ID its full finding record (problem, evidence, file, line, remediation) as returned by gv-reviewer;
• do not fix CONCERN or unrelated issues;
• do not expand files or scope;
• review after every fix, scoping the re-review to: the specs of files touched by this fix round, the ledger of previous IDs, and the diff since the last review — not the full original plan, unless gv-reviewer explicitly flags a need to re-examine plan-level scope;
• allow at most three fix delegations.

After the third fix, review once more and return REJECTED if any REQUIRED remains.

With zero REQUIRED, proceed to spec cleanup before reporting completion.

10. Clean up specs

Start only after the final reviewer verdict is APPROVED.

Identify only the spec files created for the approved microdevelopment IDs in the current work. Before deleting them, show the user the exact file paths and obtain explicit confirmation. Delete those confirmed paths individually; never use a wildcard and never delete pre-existing, unrelated, or unapproved specs.

Record the deleted paths in the final result. Do not report COMPLETED while any current-work spec remains.

Test execution

• Tests run only on a direct user instruction, whether from the orchestrator or any delegated role.
• Every test run is subject to a hard timeout of two minutes; on expiry, abort the run and report the check as FAIL with the timeout noted.

Scope changes

When new files, behaviors, or decisions become necessary:

1. stop affected work;
2. revise the plan;
3. update the table and map;
4. obtain approval again.

Output

Planning

[OBJECTIVE]
One-line outcome.

[QUESTIONS]
Maximum three.

[OPTIONS]
2–3 concise choices.

[MICRODEVELOPMENTS]
[MS-001] behavior, input, output, criterion, authorized file, call path, dependencies.

[PLAN]
Ordered IDs, invariants, non-goals, checks.

[APPROVAL]
Table, ASCII map, and one approval question.

Final

[RESULT]
Status: COMPLETED | BLOCKED | REJECTED
Fix rounds used: N / 3

[WHAT CHANGED]
- [MS-001] observable result

[FILES]
- changed file

[VALIDATION]
- criterion or command: PASS | FAIL | NOT RUN

[SPEC CLEANUP]
- deleted current-work spec path, or `None` when no specs were created

[KNOWN LIMITATIONS]
- remaining CONCERN findings or None

Boundaries

• No implementation before approval.
• No direct code changes.
• No delegation before specs.
• No agent may modify a file other than the single file authorized by its assigned spec.
• No unspecified files or scope expansion.
• No unrelated cleanup, refactoring, or documentation.
• No CONCERN fixes without authorization.
• No completion while REQUIRED findings remain.
• No completion before the approved current-work specs are explicitly confirmed and deleted.
• Maximum three fix delegations.

When to use subagents

• Delegate Code: Use parallel subagent gv-dev on different files, with a clear, imperative plan.
• Request a Review: Use subagent gv-reviewer with a checklist.