| name | sdcorejs-brainstorming |
| description | Discovery and requirement-confirmation gate before spec. Use for open-ended ideas, compare approaches, missing blockers, or CRUD/entity/screen/module/backend/site/test/product/design/doc/workflow requests across Angular, NestJS, Next.js, React, Node, fullstack, documentation, workflow, test, product, design, and generic/general tracks. Detects track/profile, explores only when unsettled, then confirms minimum inputs for spec. Runtime-localized. |
Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.
01 - Brainstorming
Shared Protocols
Before executing this skill:
- Read and apply
../_refs/shared/tasklist.md for non-trivial execution tasks.
- Read and apply
../_refs/shared/persona.md if a project persona exists.
- Read and apply
../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
- Current user request, current files, diffs, logs, failing tests, and command output override stored context.
- Before presenting user-facing choices, approval gates, yes/no questions, or mode selections, read and apply
../_refs/shared/user-choice-prompt.md so options are presented as sequential numbered choices.
Purpose
Turn a request into a confirmed requirement contract. This skill now owns both jobs that used to be split:
- Explore options when the direction is still open.
- Confirm the blocking inputs needed before
sdcorejs-spec.
Output dialogue only. Do not write specs, plans, or code here.
Process
0. Detect execution context
Detect the target project root, target_root_kind, track, and
stack_profile before asking blockers. Use ../_refs/shared/project-context.md
with:
caller_context: sdcorejs-brainstorming
context_mode: summary-read | code-map-readonly
side_effects_allowed: false
Use summary-read or code-map-readonly by default. If the summary is missing,
stale, or contradictory, keep reading targeted files; missing context is not
permission to write .sdcorejs/summary.md. Never use summary-refresh from
brainstorming unless the user explicitly approves a context write and the
authoring-repo guard says the target can be written.
TARGET_ROOT=$(git rev-parse --show-toplevel)
cd "$TARGET_ROOT"
If multiple app roots exist, ask the user which root to target with a numbered
list and short aliases from ../_refs/shared/user-choice-prompt.md. If no known
stack is detected, keep TRACK=generic; sdcorejs-execute-plan can still run
the approved plan through the harness fallback.
Classify target_root_kind:
target-project - normal app/project root.sdcorejs-agent-authoring-repo - this repository or a checkout containing
the SDCoreJS skill-pack sources.skill-pack-authoring-repo - another reusable skill/plugin pack.unknown - no reliable root evidence.
Writing to an authoring repo requires explicit confirmation that the authoring
repo itself is the target. Brainstorming remains read-only either way.
0.1 Stack profile classification
Set track, stack_profile, profile_confidence, and profile_evidence from
current evidence. If sdcorejs-explore already produced explore_context,
consume stack_profiles and profile_evidence as evidence, not truth.
Angular profiles:
core-ui-angular: Angular plus an installed dependency/import of
@sdcorejs/angular.legacy-core-ui-angular: Angular plus an installed dependency/import of
@sd-angular/core.plain-angular: Angular signals such as angular.json, @angular/core,
components, routes, or Angular tests, with no Core UI package/import evidence.migration-request: the user explicitly asks to install, migrate, or adopt
SDCoreJS Core UI or another framework convention not currently present.
Do not classify an Angular project as Core UI from angular.json alone. Do not
classify an Angular project as Core UI from @angular/core alone.
NestJS profiles:
sdcorejs-nestjs: NestJS plus @sdcorejs/nestjs or strong SDCoreJS Nest
conventions already present.plain-nestjs: NestJS signals such as nest-cli.json, @nestjs/*,
modules/controllers/providers, or Nest tests, with no SDCoreJS Nest evidence.
Do not assume TypeORM, PostgreSQL, Zod, SdContext, @HasPermission, or
@sdcorejs/nestjs for plain-nestjs unless detected or selected.
Next.js profiles:
nextjs-build-website: Next.js plus strong public-site/build-website
evidence such as [locale] routes, typed i18n navigation, content/public-site
structure, or prior sdcorejs-nextjs build-website context.plain-nextjs: Next.js signals such as next.config.*, next dependency,
app/pages router files, page.tsx, layout.tsx, route.ts, or tests, with
no build-website evidence.react-next-generic: use this when Next.js is present but the request is
generic React/dashboard/app work and build-website profile is absent.
Do not assume [locale], setRequestLocale, sitemap/public-site metadata,
typed i18n navigation, or content folders for plain-nextjs. Do not assume
build-website conventions for generic Next.js apps.
Do not assume [locale] routes or build-website conventions unless
nextjs-build-website evidence is present or the user selected that migration.
React and general profiles:
react-vite: Vite config plus React dependency.react-cra: react-scripts.node-general: Node/package project without a stronger framework profile.general: no known stack evidence.unknown: conflicting or insufficient evidence.
Allowed track values:
angular, nestjs, nextjs, react, node, fullstack, product,
design, documentation, workflow, test, general.
1. Load context cheaply
Read only what changes the questions:
- Latest 3
.sdcorejs/docs/<track>/*.md, if present.
.sdcorejs/memories/<track>/*.md frontmatter; load relevant bodies only.- Latest approved specs/plans frontmatter under
.sdcorejs/specs/<track>/ and .sdcorejs/plans/<track>/.
- For angular / nestjs / nextjs:
../_refs/sdlc/<track>.md.
- For test:
../_refs/shared/testing-philosophy.md, then the target stack test ref when known.
- For product: latest
.sdcorejs/docs/product/*.md plus related specs/plans.
package.json, lockfiles, and workspace config only enough to identify
package manager/script evidence; do not run installs or mutate dependencies.
2. Decide explore mode vs confirm mode
Use explore mode when the request is unsettled:
- The user describes a goal, not concrete artifacts.
- There are multiple plausible approaches.
- The user compares options or says they are unsure.
- For nextjs, industry / audience / page set is unknown.
- For angular / nestjs, module ownership or workflow shape is unclear.
- For test, the user provided selectors or an inspector export without test cases and assertions.
Use confirm mode when the user already gave concrete artifacts and the remaining work is to lock blockers.
3. Explore only when needed
When in explore mode:
- Ask at most one targeted question if the answer changes the option set.
- Present 2-3 approaches with stable numeric selectors (
1/2/3) and tradeoffs.
- Recommend one approach with a short reason tied to the user's goal.
- Ask for direction confirmation and state that the user can reply with the selector, alias, or "you decide".
Do not continue to blocker confirmation until the direction is selected or the user explicitly says "you decide".
Optional Visual Companion
Use the visual companion as an optional browser-based aid during brainstorming
when seeing a mockup, wireframe, layout, diagram, flow, or side-by-side
comparison would make the next decision clearer than text.
The visual companion is a tool, not a mode. Accepting it means it is available
for suitable visual questions; it does not mean every brainstorming step should
use the browser.
Do not offer the visual companion upfront. First understand the user's request,
project context, constraints, and current design question. Offer it only when
the next decision would genuinely be clearer if shown visually, such as choosing
between layouts, UI flows, component structures, information architecture,
navigation models, visual hierarchy, architecture boundaries, data flows, state
machines, entity relationships, or side-by-side design directions.
When that first genuinely visual decision appears, send the offer as its own
standalone message using two numbered choices. Runtime-localize the prose while
preserving the two-choice shape:
The next decision may be easier to understand if shown visually as a mockup,
diagram, or browser comparison. Which direction do you want?
1. Use visual companion to preview visual options before approving the design
2. Do not use visual companion; continue brainstorming in text + TDD
Reply with `1` or `2`.
Do not combine this offer with a clarifying question, implementation plan,
design summary, or any other content. Wait for the user's response.
If the user chooses option 1:
- Read
visual-companion.md before proceeding.
- Locate the visual companion reference, runtime, and templates using the
current skill/project convention.
- Start or use the available visual companion runtime if one exists.
- If no browser runtime exists, create static HTML or Markdown visual artifacts
using the current project convention.
- Use the visual companion per question, not per session.
- Create one visual decision screen at a time.
- Prefer 2-3 options, not many options.
- Ask the user to review the screen and respond in the main conversation.
- Treat browser clicks or visual selections as supporting feedback, not as the
only source of truth.
- Merge visual feedback with the user's written response before updating the
design.
If the user chooses option 2:
- Continue text-only.
- Do not offer the visual companion again unless the user asks for it or a later
design decision would be extremely unclear without visual support.
Per-question rule:
- Use browser visuals for UI mockups, wireframes, layout comparisons, navigation
structures, architecture diagrams, data-flow diagrams, state machines, entity
relationships, spatial relationships, before/after UX comparisons, and visual
polish questions.
- Use text for requirements, scope, API design, data model decisions, TDD
strategy, trade-off lists, business rules, acceptance criteria, and
implementation sequencing.
A UI-related topic is not automatically a visual topic. "What should this
dashboard do?" is text. "Which dashboard layout feels clearer?" is visual.
The main conversation remains the source of truth. Browser clicks, UI
selections, or visual-only feedback are supporting signals. If visual feedback
conflicts with the user's written response, prioritize the written response.
The visual companion must never bypass the normal sdcorejs-brainstorming gate:
- Understand context.
- Clarify intent and constraints.
- Propose options.
- Get design approval.
- Convert the approved direction into acceptance criteria and testable
behavior.
- Only then move to implementation planning and TDD.
4. Confirm blockers
Ask grouped blocking questions, 3-4 related questions per turn. Reuse answers
already present in the conversation or artifacts. When a blocker has known
alternatives, label them with short selectors so the user can reply quickly.
Blockers must be profile-aware. Ask only for decisions that affect
implementation correctness, security, public API, data model, irreversible
scope, verification, or user-visible behavior. For non-technical users,
translate technical consequences into product decisions.
Minimum blockers by profile/context:
| Context/profile | Required before spec |
|---|
core-ui-angular / legacy-core-ui-angular | module, entity/screen, fields or visible data, layout, workflow/actions, permissions if applicable, Core UI reuse expectations |
plain-angular | local module/screen, installed UI library or existing components, visible data, workflow/actions, route/state shape, verification; do not ask Core UI/admin-screen blockers unless migration or Core UI was explicitly selected |
sdcorejs-nestjs | module, entity/resource, persistence, transaction style, endpoint/action set, permission/profile decisions |
plain-nestjs | resource/API shape, persistence actually present, endpoint/action set, validation/auth expectations, verification; do not ask SDCoreJS Nest/TypeORM/PostgreSQL blockers unless detected or selected |
nextjs-build-website | domain or temporary production URL, target audience, page set, contact channel, languages, hosting/caching, OG/SEO expectations |
plain-nextjs / react-next-generic | app/dashboard/page intent, routes/components, data source, auth/session expectations, rendering constraints, verification; do not ask build-website/domain/i18n blockers unless public-site delivery is intended |
react-vite / react-cra | feature/component, state/data source, routing, styling system, test runner |
node-general / general | goal, files/areas in scope, constraints, acceptance criteria, verification command or manual check |
| test | target stack, test level, subject under test, cases with expected results, data/auth/env, selector/source inventory, reuse vs new fixtures |
| product | feature name, business goal, users/personas, scenarios, acceptance criteria seed, source artifacts, impacted tracks, UAT expectations |
Also ask the coverage approach once:
post-hoc (default for UI/content scaffolding).TDD (default for service logic, validators, workflows, transactions).test-plan-only when the requested output is a test plan.not-applicable for pure product/design/discovery artifacts.
Record this answer for sdcorejs-plan.
5. Infer then confirm
When a semantic default is obvious, propose it instead of asking from scratch:
- Entity fields from entity name.
- Next.js page set from industry and goal.
- Test cases from acceptance criteria or an inspector export.
- Product acceptance criteria from approved requirements, marking inferred items for confirmation.
- Generic harness verification from scripts in
package.json.
Always present inferred values for confirmation before locking them.
6. Output the requirement contract
End with a concise confirmed summary in the user's language and a structured
requirement_context block. Do not persist it unless a later write-approved
skill owns the artifact.
- Track/context.
- Target root and
target_root_kind.
stack_profile, confidence, and evidence.- Chosen direction.
- Required inputs.
- Defaults accepted.
- Coverage approach.
- Acceptance criteria seed.
- Open questions, if any.
If any minimum blocker remains unanswered, stop here and ask only for the missing blocker. When all blockers are confirmed, hand off to sdcorejs-spec.
Use this schema:
requirement_context:
source: sdcorejs-brainstorming
requirement_id: <stable id>
contract_id: <stable id shared by spec/plan/execute>
target_root: <absolute or repo-relative target>
target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
track: angular | nestjs | nextjs | react | node | fullstack | product | design | documentation | workflow | test | general
stack_profile: core-ui-angular | legacy-core-ui-angular | plain-angular | sdcorejs-nestjs | plain-nestjs | nextjs-build-website | plain-nextjs | react-vite | react-cra | react-next-generic | node-general | general | migration-request | unknown
profile_confidence: high | medium | low
profile_evidence:
- <dependency/config/file/import evidence>
user_goal: <summary>
user_type: technical | non-technical | mixed | unknown
problem_statement: <summary>
success_outcome: <summary>
in_scope:
- item: <scope item>
source: explicit | inferred | defaulted
out_of_scope:
- item: <scope item>
source: explicit | inferred | defaulted
decisions_confirmed:
- decision: <name>
value: <value>
source: explicit | inferred | defaulted
assumptions:
- assumption: <text>
source: inferred | defaulted
requires_confirmation: true | false
blockers:
resolved:
- item: <text>
unresolved:
- item: <text>
coverage_approach: post-hoc | tdd | test-plan-only | not-applicable | unknown
visual_companion:
offered: true | false
selected: true | false
artifact_write_approved: true | false
redaction_applied: true | false
next_skill: sdcorejs-spec
Redact secrets and PII before the context is shown or passed along. Never store
secret values, credentials, tokens, API keys, database URLs, JWTs, cookies,
customer PII, production payloads, or sensitive logs in requirement/spec/plan
contexts. For env requirements, record key names only and use [REDACTED] for
values.
Rules
Must do
- Keep the user's language at runtime.
- Preserve locale-specific marks in generated labels and prose.
- Use English identifiers, permission codes, and route paths.
- Block
sdcorejs-spec until minimum blockers are confirmed.
- Save durable repeated preferences through
sdcorejs-explore (memories-write-approved) only when relevant and approved.
- Preserve
contract_id, target_root, target_root_kind, track,
stack_profile, explicit user decisions, inferred/defaulted assumptions, and
profile evidence for downstream skills.
- Keep visual companion artifact writes response-only unless
visual_companion.artifact_write_approved is true.
Must not
- Generate code, specs, plans, or commits.
- Do not write specs, plans, or code from brainstorming.
- Do not write
.sdcorejs/summary.md, specs, plans, visual companion files, or
durable memories by default.
- Ask architecture questions to a non-tech persona when a safe default exists.
- Show angular blockers to nextjs, or nestjs blockers to test.
- Force SDCoreJS/Core UI/TypeORM/build-website assumptions onto plain profiles.
- Dump every question at once.
- Treat "thanks" or silence as approval.
Hand-off
Pass sdcorejs-spec this context:
- target root
- target root kind
- detected context/track
- stack profile and profile evidence
- confirmed
requirement_context
- chosen direction and tradeoffs considered
- source artifacts provided by the user
- coverage approach
- explicit decisions, inferred/defaulted assumptions, unresolved blockers, and
redaction status
Cross-references
../_refs/sdlc/<track>.md - angular / nestjs / nextjs discovery, spec, and plan patterns../_refs/shared/testing-philosophy.md - test-track principlessdcorejs-product - product ledger and traceability reviewsdcorejs-spec - writes and reviews the spec gatesdcorejs-explore (memories mode) - durable project preferences
