Brainstorming

The Process

Understanding the idea:

• Check current project state first (files, docs, recent commits)
• Read relevant authority docs before asking deep questions
• Use existing canonical terms in questions, options, scenarios, and the spec. If terminology crystallizes or conflicts, compose establishing-project-context; do not leave the resolution only in the spec.
• If the request is diagnosis/root-cause/follow-up to an approved plan → route to correct workflow
• If the request spans multiple independent subsystems → flag and decompose first
• Ask clarifying questions one at a time, prefer multiple choice
• Separate facts, assumptions, unknowns while exploring

Working artifacts: Keep four drafts: TaskIntentDraft (outcome, goal, success evidence, stop condition, non-goals, scope, risks), BaselineReadSetHint (candidate docs, authority gaps), BaselineUsageDraft (required refs, optionally delivered context refs, acknowledged-before-plan refs, cited refs, missing refs, advisory decision), and ImpactStatementDraft (affected layers, owners, invariants, compat, non-goals). Refresh when scope changes.

Compact output contract: Aegis Visibility, TaskIntentDraft, BaselineReadSetHint, BaselineUsageDraft, Requirement Ready Check, ImpactStatementDraft, Existence Check, Product Risk Lens, Architecture Integrity Lens, Prior-Art & Reuse Lens, Baseline Role Alignment, Plan-Time Complexity Check, Options, and Decision Needed. Use this compact shape before expanding into a full design structure.

Aegis Visibility for this workflow names why design/spec clarification comes before implementation and what drift, overbuild, wrong-owner, or missing acceptance risk that restraint reduces. Keep it natural and task-specific; do not turn it into a fixed skill trace.

Use a compact BaselineUsageDraft whenever the design direction depends on specific baseline docs or current-authority refs:

BaselineUsageDraft:
- Required baseline refs:
- Delivered context refs:
- Acknowledged before plan refs:
- Cited in design refs:
- Missing refs:
- Decision: continue | needs-baseline-readback | needs-verification | pause-for-user | blocked

Delivered context refs is optional host-projected bookkeeping only. It is not authoritative proof that a host injected or the model internally consumed a context payload. The artifact exists to make baseline/context attention drift visible before the design is recommended or approved.

Use a compact Requirement Ready Check before recommending a design when the requirement is not already confirmed and complete:

Requirement Ready Check:
- Requirement source refs:
- Goals and scope refs:
- User / scenario refs:
- Requirement item refs:
- Acceptance / verification criteria refs:
- Open blocker questions:
- Decision: ready | needs-source | needs-goal-alignment | needs-scenario | needs-acceptance-criteria | needs-clarification | needs-user-decision | blocked

Treat task intent, conversation, source documents, and agent inference as candidate requirement sources until project authority confirms them. If the decision is not ready, keep the design at proposal/spec clarification level; do not turn the gap into implementation tasks.

Existence Check: Before recommending an approach that adds a new owner, skill, artifact, host adapter, fallback, compatibility path, workflow step, or benchmark metric, check whether it needs to exist. Use docs/current/AEGIS_MINIMALITY_REFERENCE.md as the reference. Do not force this onto ordinary feature design that reuses existing owners and artifacts.

Existence Check:
- Proposed new surface:
- Existing owner / reuse candidate:
- Why existing surface is insufficient:
- Creation proof:
- Entropy / retirement impact:
- Decision: reuse-existing | add-with-proof | defer | reject | needs-first-principles-review

If the decision is reuse-existing, recommend the reuse path instead of a new surface. If the decision is add-with-proof, carry the proof, verification signal, and any retirement trigger into the design/spec.

Product Risk Lens: For ambiguous product, feature, UI, workflow, or architecture choices, add a compact review lens, not persona roleplay:

Product Risk Lens:
- Value:
- Non-goals:
- Trade-offs:
- Decision needed:

This is a review lens, not persona output. It does not override baseline evidence, approved requirements, or current authority docs; it only makes the product risk and decision point visible before implementation.

Plan-Time Complexity Check: Before choosing an implementation direction for medium/high work, inspect the likely owner files and current shape. This is an advisory design pressure check, not a gate and not completion authority. Do not force it onto tiny low-risk edits.

Use using-aegis/references/complexity-governance.md for the shared artifact classes, pressure-signal interpretation, and over-budget handling.

Complexity Budget:
- Artifact class:
- Target files / artifacts:
- Current pressure:
- Projected post-change pressure:
- Budget result: within-budget | at-risk | over-budget
- Planned governance:

Plan-Time Complexity Check:
- Better file boundary:
- Recommendation: edit-in-place | extract helper | add owner file | split task | defer refactor

Exploring approaches: Propose 2-3 approaches with trade-offs and recommendation. Make scope boundary explicit: what's in, what's deferred, what belongs elsewhere.

Before approach selection, use Existence Check for any proposed new surface. Escalate to first-principles-review and its Decision Hygiene Review when the candidate direction still introduces a new owner, duplicate owner, fallback, adapter, compat-only carrier, delete-first question, unverified assumption, or "long-term stable" claim after the existence check. Do not make either check a universal design ceremony; return to this workflow once the decision surface is clean.

When the central decision is internal retirement vs compat retention vs persistent-state confirmation, compose anti-entropy-governance. It classifies the deletion target, chooses delete-first | compat-exception | confirmation-first, and keeps destructive authority outside the design skill.

Use the narrower Architecture Integrity Lens when the main risk is not broad strategy but architecture coherence: unclear canonical owner, responsibility overlap, caller-side fallback, stale path carrying real logic, or a possible higher-level owner / contract / source-of-truth simplification. The lens should answer invariant, canonical owner / contract, responsibility overlap, higher-level simplification, retirement / falsifier, and verdict before the approach is recommended.

Prior-Art & Reuse Lens: When a candidate approach would introduce a new mechanism, protocol, artifact shape, or nontrivial interaction pattern, check proven external practice before inventing one. This lens is behavior-triggered: research precedents when the direction is novel for the project, plausible approaches remain after internal reuse checks, or the domain sits outside current repository evidence. Do not run research ceremony for routine work that already maps to well-known framework patterns, and do not let an unavailable web/search tool stall approach selection.

Prior-Art & Reuse Lens:
- Searched precedents: <bounded sources; index-first summary; cite anchor per claim>
- Adopt verbatim: <proven pattern + source>
- Adapt with reason: <tailored part -> project constraint / non-negotiable it maps to>
- Reject with reason: <project fact that makes the pattern inapplicable>
- Degraded: <no web/search tooling -> external basis unknown; internal-only evidence stated>

Search results are evidence candidates, not prompt payload: summarize index-first and cite anchors instead of pasting raw pages. An "industry standard" claim without a citable anchor stays unknown. Every adapt/reject decision binds to a named project constraint or fact, not taste. The lens feeds only the approach recommendation; it stays advisory and grants no completion authority.

Baseline Role Alignment: When a question may involve both "what should be built" and "where it should live", keep requirement truth separate from architecture truth:

Baseline Role Alignment:
- Product / Requirement Baseline:
- Architecture / Runtime Boundary Baseline:
- Result: aligned | Design Defect | Implementation Drift | missing-authority | needs-clarification
- scope: requirements | architecture | both
- Next action:

Use Design Defect when the relevant requirement, design, or baseline is wrong. Use Implementation Drift when the work deviates from a correct unchanged baseline. Architecture Defect and Architecture Drift remain compatibility aliases for architecture-scoped Design Defect and architecture-scoped Implementation Drift. This is a review lens, not a runtime gate or completion authority.

Presenting the design: Scale sections to complexity. Cover only the surfaces that matter: architecture, components, data flow, error handling, testing, compatibility boundary. Get approval for the design before implementation when behavior, contract, architecture, or user-facing flow is being decided.

ADR signals: When the design/spec touches durable architecture surfaces (owner, public contract, artifact shape, dependency direction, source-of-truth, host compatibility, runtime-ready boundary, fallback, adapter, or retirement schedule), mark the ADR signal, source refs, real alternatives, and expected baseline-sync question for later completion. Do not create accepted architecture memory from unexecuted ideas.

Design for isolation: Each unit = one clear purpose, well-defined interface, testable independently. Can someone understand it without reading internals? Can you change internals without breaking consumers?

Existing codebases: Follow existing patterns. Include targeted improvements only when they serve the current goal. If the design touches contracts, compat, fallbacks, or duplicated owners → call it out directly.

Conditional Detailed Guidance

For user-facing interface or interaction design, compose ui-ux-governance; carry scoped experience rules into the existing acceptance criteria. This skill retains design approval and handoff ownership.

Conditional design probe, scenario profile, and workspace/spec documentation detail maps to explicit headings below.

Read only the evidence-matched section of expanded-design-guidance.md:

• ## Design Probe only when existing evidence is insufficient and a bounded probe can change the design direction;
• ## Software Scenario Profiles only after the work is classified as one of its named scenario classes and profile-specific state/risk coverage is useful;
• ## Documentation And Workspace Bootstrap only after the Doc Necessity Gate selects a spec or workspace artifact;
• ## Spec Self-Review only for a written Design Spec; and
• a named baseline template section only when initializing that exact file.

Do not load the reference for route selection, first-turn clarification, route-away cases, or an active Grilling Mode interview. The reference supplies detail; this main skill continues to own routing, design approval, and handoff.

Design Ready And Design Complete

Approach selection is ready when:

• the desired outcome and primary scenario are known;
• scope and non-goals are explicit;
• current behavior and the target delta are grounded;
• key invariants and the likely canonical owner are identified;
• at least one observable acceptance criterion exists;
• no open unknown can still change the approach category.

Not every unknown must be eliminated; only decision-changing unknowns block convergence.

The design can hand off when all applicable conditions hold:

• the selected approach and canonical owner are explicit;
• fixed behavior/contract and implementation-owned choices are separated;
• alternatives were materially compared or excluded by evidence;
• critical assumptions have evidence or explicit acceptance;
• failure/recovery and consumer impact are covered where applicable;
• acceptance criteria are observable and usable by verification;
• new owners, fallbacks, adapters, compatibility, or persistence have creation proof and retirement/rollback treatment;
• every user-owned decision has real user approval.

Design Complete is method readiness, not completion authority. Transition to writing-plans only after these conditions hold; do not carry unresolved decision-changing unknowns into the plan.

After the Design

After approval, Write the validated spec artifact when needed. If the Doc Necessity Gate selects workspace or spec documentation, read the applicable sections of expanded-design-guidance.md; otherwise keep the accepted design in-session. When workspace support is selected, its helper remains outside the target project and is invoked as <aegis-workspace-helper>.

Aegis Project Workspace: workspace creation and spec persistence remain conditional on the Doc Necessity Gate and project authority.

For a Design Spec, complete its self-review and obtain explicit user review before planning. Apply requested changes and review again. A small Spec Brief that only pins medium-task acceptance may use concise review unless project authority requires a formal gate.

Implementation:

• Invoke the writing-plans skill to create a detailed implementation plan
• Do NOT invoke any other skill. writing-plans is the next step.

Key Principles

• One question at a time - Don't overwhelm with multiple questions
• Multiple choice preferred - Easier to answer than open-ended when possible
• YAGNI ruthlessly - Remove unnecessary features from all designs
• Explore alternatives - Always propose 2-3 approaches before settling
• Incremental validation - Present design, get approval before moving on
• Be flexible - Go back and clarify when something doesn't make sense