sdcorejs-brainstorming

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:

1. Read and apply ../_refs/shared/tasklist.md for non-trivial execution tasks.
2. Read and apply ../_refs/shared/persona.md if a project persona exists.
3. Read and apply ../_refs/shared/project-context.md for project memory, resume checkpoints, summaries, specs/plans, tasks, and relevant memories.
4. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
5. 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:

1. Explore options when the direction is still open.
2. 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:

1. Ask at most one targeted question if the answer changes the option set.
2. Present 2-3 approaches with stable numeric selectors (1/2/3) and tradeoffs.
3. Recommend one approach with a short reason tied to the user's goal.
4. 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:

1. Understand context.
2. Clarify intent and constraints.
3. Propose options.
4. Get design approval.
5. Convert the approved direction into acceptance criteria and testable behavior.
6. 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 principles
• sdcorejs-product - product ledger and traceability review
• sdcorejs-spec - writes and reviews the spec gate
• sdcorejs-explore (memories mode) - durable project preferences