brainstorming

HOTL Brainstorming

Overview

Turn ideas into designs with explicit HOTL contracts. Ask questions one at a time. Present design for approval before any implementation.

Do NOT write any implementation code until the design is approved and writing-plans has generated the executable workflow.

Process

1. Explore context (cheap preflight first)

   Phase 1 — Cheap preflight (Glob only, current project directory):

   • If user's message references a doc path → read it
   • Check for canonical design docs in docs/designs/*.md
   • Check for legacy design docs in docs/plans/*.md
   • Check for source code, config manifests, or project-specific config files
   • "Relevant context" means: design docs, source code, configuration manifests, or project-specific config. Files like README.md, .gitignore, LICENSE, and scaffolding boilerplate do not count.

   Phase 2 — Branch on result:

   • Relevant local context found: Read the most recent 1-2 design docs from canonical or legacy locations, inspect only relevant in-project files, and optionally review recent commits (only if the directory is a git repo).
   • No relevant local context found: State: "This appears to be a greenfield or effectively empty project, so I'm skipping deep context scanning and moving to clarifying questions." Proceed directly to step 2.

   Hard rule: Never scan parent directories, sibling folders, or workspace-wide paths unless the user explicitly provides a path.

2. Determine scope — decide between feature, phase, or initiative before the clarifying-questions loop. Scope shapes every downstream step: output path, contract structure, depth of inquiry.

   Scope choices:

   • feature — one feature, one bug fix, one refactor. Output: docs/designs/YYYY-MM-DD-<slug>-design.md (dated, tactical).
   • phase — one slice of a multi-phase initiative. Same output family as feature: docs/designs/YYYY-MM-DD-phase-N-<slug>-design.md.
   • initiative — a multi-phase project (v1/v2, platform migration, enterprise rebuild). Output: docs/designs/<topic>.md (undated, durable, strategic).

   Default: feature. If the user's initial message clearly describes a feature, proceed with feature scope without blocking for input. Optionally acknowledge in one line ("Treating as feature scope; say so if this should be a phase or initiative"). Do not pause the flow.

   Ask the scope question explicitly when the request is ambiguous or multi-phase (e.g., "migrate v1 to v2", "platform rebuild", "rework across services"). Present the three choices with feature as the pre-filled default and wait for the user's answer before continuing.

   For initiative scope, load the strategic-design template once at session start. Resolve adapters/strategic-design.template.md in this order (same pattern used for document-lint.sh and hotl-config.sh — see skills/document-review/SKILL.md):

   1. If you are working in the hotl-plugin repo itself, use adapters/strategic-design.template.md
   2. Codex native-skills install: ~/.codex/hotl/adapters/strategic-design.template.md
   3. Codex plugin install: ~/.codex/plugins/hotl-source/adapters/strategic-design.template.md
   4. Codex plugin cache fallback: ~/.codex/plugins/cache/codex-plugins/hotl/*/adapters/strategic-design.template.md
   5. Cline install fallback: ~/.cline/hotl/adapters/strategic-design.template.md
   6. Claude Code plugin fallback: ~/.claude/plugins/hotl/adapters/strategic-design.template.md

   Read the resolved template once at session start — its section structure (problem, vision, non-goals, stakeholders, architecture, phase breakdown, risks) becomes the skeleton of the design doc you produce. Do not assume adapters/strategic-design.template.md exists in the repo being worked on.

   For initiative scope, resolve the output directory via hotl-config-resolve.sh:

   bash <resolved-hotl-config-resolve.sh> get designs_dir --default=docs/designs
   

   Resolve hotl-config-resolve.sh via the same six-location order. The default is docs/designs when no .hotl/config.yml is present; opted-in projects may override via that config.

3. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria. Prefer multiple-choice when the likely answer space is known (e.g., "Which constraints apply? (a) Must not break existing API (b) Backward-compatible (c) Performance-sensitive (d) Other"). Fall back to open-ended only when the problem is unusual or exploratory.

4. Propose 2-3 approaches — with trade-offs and recommendation

5. Present design in sections — get approval after each section

6. Define HOTL contracts — always include all three:

Intent Contract

intent: [one sentence goal]
constraints: [what must not change/break]
success_criteria: [how we know it's done]
risk_level: low | medium | high

Verification Contract

verify_steps:
  - run tests: [test command]
  - check: [what to inspect]
  - confirm: [success signal]

Governance Contract

approval_gates: [list of steps requiring human review]
rollback: [how to undo if something goes wrong]
ownership: [who is accountable]

7. Write design doc — path depends on scope:

   • feature scope: save to docs/designs/YYYY-MM-DD-<slug>-design.md (dated, tactical).
   • phase scope: save to docs/designs/YYYY-MM-DD-phase-N-<slug>-design.md (dated, tactical).
   • initiative scope: save to <designs_dir>/<topic>.md (undated, durable). <designs_dir> is the value returned by the step-2 resolver (default docs/designs). Follow the section structure of the strategic template loaded in step 2.

   Always write YAML frontmatter with the HOTL marker. Every saved design doc MUST start with frontmatter declaring at minimum:

   ---
   design_type: <feature|phase|initiative>   # match the scope chosen in step 2
   created_at: YYYY-MM-DD
   ---
   

   The design_type field is the deterministic signal that opts the doc into HOTL strict lint (document-lint.sh SKIPs unmarked docs). Without it, the doc is treated as non-HOTL and routes through generic AI review only.

8. Self-check the design doc — before presenting for human approval, review the saved design doc for: missing constraints, vague success criteria, contract mismatches (do verification steps actually test the intent?), risk_level appropriateness, and scope creep. Fix any issues found. Lightweight: 1-2 passes by default, max 3 only if real issues are found. Do not ask the user to review — this is an internal quality pass.

   Run document-lint on the saved design doc as part of this self-check. Resolve scripts/document-lint.sh via the standard six-location order, then:

   bash <resolved-document-lint.sh> <saved-design-path>
   

   The lint emits two stable warning shapes for feature/phase docs:

   category=structure severity=warning design_type=<resolved>
   message="missing required section: ## <name>"
   
   category=implementation-leakage severity=warning design_type=<resolved> line=<n>
   message="<short description>"
   

   Apply the 5-step self-check behavior to surfaced warnings:

   1. Run document-lint.sh on the saved design doc.
   2. Surface warnings to the user before asking for approval.
   3. Fix warnings that clearly violate the design/plan boundary.
   4. Justify a warning only when the flagged content sits inside a clearly delimited example block — a Markdown blockquote (> Example: ...) or a section whose heading includes the word Example. All other findings must be fixed.
   5. Do not block approval unless the user decides the warnings are blocking.

   Loop bound: This 5-step procedure runs at most once per self-check pass; the parent self-check (step 8) caps the total at 3 passes before stopping.

   Lint exits 0 even when these warnings are emitted (warning-only contract this pass). Initiative / architecture / contract / reference docs receive neither check; the lint emits no category=structure or category=implementation-leakage lines for them.

9. Invoke writing-plans — transition to implementation planning (feature/phase scope only; initiative designs decompose into child phase plans that each go through their own brainstorming → writing-plans cycle).

Doc-discipline rules

For design_type ∈ {feature, phase} docs, write the body using these seven required sections in fixed order. Phase 1 lint enforces presence only; out-of-order or extra sections are not flagged this pass but the prose order below is the canonical convention:

1. ## Intent Contract
2. ## Verification Contract
3. ## Governance Contract
4. ## Scope (in / out, table form preferred)
5. ## Decisions (# / decision / choice / rejected alternatives, table form preferred)
6. ## Surface (APIs / storage / components / files-touched, paragraph each)
7. ## Risks & Open Questions

Initiative / architecture / contract / reference docs are durable references; they may legitimately include deeper technical shape. The lint defers any rules for them this pass.

Implementation-leakage anti-patterns

A design doc says shape; the workflow file and the code say exact bytes. The following patterns belong in writing-plans output (or in code itself), not in the design — the lint warns when they appear in feature/phase design bodies:

Pattern	Example	Why it doesn't belong in design
File:line references	cli.py:16, auth.ts:204	Line numbers rot the moment code moves; pin to workflow steps instead.
Long fenced code blocks (>10 content lines)	a 30-line Python snippet	Design shows shape; full implementation goes in workflow tasks or code.
Dense flag lines (≥6 -- tokens)	docker run --network=none --cap-drop=ALL --read-only --tmpfs /tmp ...	Argv assertions go in workflow steps and tests, not design surface.

When a design doc must reference one of these (e.g., as an illustrative example), the warning is acceptable and the agent should justify it during the self-check (step 8) rather than rewrite the design.

Doc-type detection

1. Frontmatter is the deterministic signal. A doc is HOTL-managed only when its frontmatter declares design_type: (one of feature | phase | initiative | architecture | contract | reference) or hotl_managed: true. The brainstorming skill always writes the marker; ad-hoc docs in docs/designs/ are treated as non-HOTL by default.
2. Filename pattern is a hint, not a classifier. Dated YYYY-MM-DD-*-design.md is the conventional pattern for HOTL-authored docs, but the lint still requires a frontmatter marker before applying HOTL rules. Without a marker, document-lint.sh SKIPs cleanly with a clear message and exits 0.
3. Unmarked design-folder docs route to AI review. hotl:document-review runs a generic-rubric AI review on them; document-lint.sh skips them. To opt a hand-authored doc into HOTL strict review, add design_type: <recognized-value> or hotl_managed: true to its frontmatter.

Key Principles

• One question at a time — prefer multiple-choice when practical
• YAGNI ruthlessly — remove unnecessary features
• Always propose alternatives before settling
• risk_level: high = security, auth, privacy, billing (always human-gated)