Harness Brainstorming

Harness Brainstorming

Design exploration to spec to plan. No implementation before design approval. Think first, build second.

When to Use

• Starting a new feature requiring design decisions
• When the problem space is ambiguous and needs exploration
• When multiple approaches exist and tradeoffs must be weighed
• When on_new_feature trigger fires and scope is non-trivial
• NOT when the implementation path is already clear (go straight to harness-planning)
• NOT when fixing a bug with an obvious root cause (use harness-debugging or harness-tdd)
• NOT for simple refactors with no design decisions (use harness-refactoring)

Process

Iron Law

No implementation may begin before the design is approved by the human.

If you find yourself writing production code, tests, or scaffolding before sign-off, STOP. Brainstorming produces a spec document, not code.

---

Argument Resolution

When invoked by autopilot (or with explicit arguments), resolve paths before starting:

1. Session slug: If session-slug argument provided, use it for all session-scoped reads/writes ({sessionDir} = .harness/sessions/<session-slug>/). Otherwise, session-scoped paths are unavailable — fall back to global .harness/ paths.
2. Handoff output: When session slug is known, write handoff to {sessionDir}/handoff.json. Otherwise write to .harness/handoff.json (deprecated fallback).

When no arguments are provided (standalone invocation), the skill operates exactly as before — no session scoping, global paths only.

---

Phase 1: EXPLORE -- Gather Context

0a. Read STRATEGY.md if present at repo root (upstream grounding). Strategy is the durable product anchor that ranks above feature-level context — read it first so the rest of EXPLORE can cross-reference. Call read_strategy({ path: "<project-root>" }) on the harness MCP server — it returns { present, valid, doc?, error? } and runs validation + parsing inside the server so the project does not need @harness-engineering/core installed.

Fallback for environments without the MCP server (only works when core is resolvable from the project):

```bash
node -e "import('@harness-engineering/core').then(async m => {
  const v = await m.validateStrategy(process.cwd());
  if (!v.ok || !v.value.present) { console.log(JSON.stringify({ grounded: false, reason: 'absent' })); return; }
  const raw = require('fs').readFileSync('STRATEGY.md', 'utf-8');
  console.log(JSON.stringify({ grounded: true, doc: m.asStrategyDoc(m.parseStrategyDoc(raw)) }));
})"
```

Three cases:

- **Absent or invalid:** soft-fail silently. Do not block and do not warn in the spec — the skill works exactly as before when there is no strategic anchor.
- **Present and valid:** capture the `Target problem`, `Our approach`, `Who it's for`, and `Tracks` section bodies. Treat them as grounding context alongside `gather_context` outputs. The captured strategy is cited as evidence in step 1's `[evidence]` annotations of the spec output.
- **Contradiction with the user's feature description:** do NOT auto-resolve. Carry the contradiction forward as an open question into Phase 2 EVALUATE — surface it explicitly so the human can decide whether to refine the feature or update strategy via `/harness:strategy`.

1. Load project context. Call gather_context({ path: "<project-root>", intent: "<feature description>", skill: "harness-brainstorming", session: "<session-slug-if-known>", include: ["graph", "businessKnowledge", "sessions", "validation"] }). The graph context surfaces business_fact nodes relevant to the feature domain. The businessKnowledge context loads documented domain knowledge from docs/knowledge/. Use both to ground exploration in verified facts rather than assumptions. When STRATEGY.md was loaded in step 0a, treat its sections as a higher-tier grounding source than businessKnowledge — strategy reflects an explicit human commitment, knowledge is observation.
2. Read the existing codebase. Understand architecture, constraints, and conventions. Check AGENTS.md, existing specs in docs/, and relevant source files.
3. Identify the problem boundary. What exactly needs solving? What is out of scope? Write both down. Cross-reference businessKnowledge domains — if documented business rules constrain the problem, note them.
4. Check for prior art. Has this been partially solved elsewhere? Are there patterns to follow or deliberately break?
5. Assess scope. If the problem spans >3 major subsystems or >2 weeks to implement, decompose into sub-projects first.

---

Phase 2: EVALUATE -- Ask Questions and Narrow

1. Ask ONE question at a time. Ask the most important question first. Wait for the answer. Let it inform the next question. Use emit_interaction with type: 'question':

   emit_interaction({
     path: "<project-root>",
     type: "question",
     question: {
       text: "For auth, which approach should we use?",
       options: [
         { "label": "A) Existing JWT middleware", "pros": ["Already in codebase"], "cons": ["No refresh tokens"], "risk": "low", "effort": "low" },
         { "label": "B) OAuth2 via provider X", "pros": ["Industry standard"], "cons": ["New dependency"], "risk": "medium", "effort": "medium" },
         { "label": "C) External auth service", "pros": ["Zero maintenance"], "cons": ["Vendor lock-in", "Cost"], "risk": "medium", "effort": "low" }
       ],
       recommendation: { "optionIndex": 0, "reason": "Sufficient for current requirements.", "confidence": "high" }
     }
   })
   

2. Prefer multiple choice over open-ended questions. Give 2-4 concrete options with brief tradeoff notes.

3. Acknowledge answers and build on them. Do not re-ask clarified points. Track decisions as they accumulate.

4. Apply YAGNI ruthlessly. For every proposed capability, ask: "Do we need this for the stated goal, or is this speculative?" If speculative, cut it. If the human insists, note it as a future consideration.

5. Surface strategy contradictions. If Phase 1 step 0a captured a contradiction between the feature description and STRATEGY.md, ask the human about it explicitly as one of the first few EVALUATE questions. Frame it as a choice — refine the feature to align, or refine strategy via /harness:strategy — never auto-resolve. Skip this when STRATEGY.md was absent or no contradiction was detected.

6. Continue until you have enough clarity to propose concrete approaches. Typically 3-7 questions suffice. If you need >10, the scope is too large -- decompose.

Context Keywords

During Phase 2, extract 5-10 domain keywords for the spec frontmatter:

**Keywords:** auth, middleware, session-tokens, refresh-flow, OAuth2

These flow into handoff.json contextKeywords field. Select keywords that help a fresh agent understand the domain quickly.

---

Phase 3: PRIORITIZE -- Propose Approaches

1. Propose 2-3 concrete approaches. Each must include:

   • Summary: One sentence
   • How it works: Key technical decisions (data structures, APIs, patterns)
   • Tradeoffs: What you gain, lose, what gets harder later
   • Complexity: Low/Medium/High with brief justification
   • Risk: What could go wrong, what assumptions might be wrong

   Use conventional markdown for callouts:

   **[IMPORTANT]** Approach 1 trades simplicity for extensibility
   **[SUGGESTION]** Consider Approach 2 if real-time requirements emerge
   

2. Be honest about tradeoffs. Do not soft-sell a preferred approach.

3. State your recommendation and why, but defer to the human's decision.

4. Wait for the human to choose. Do not proceed until an approach is selected.

---

Phase 4: VALIDATE -- Write the Spec

1. Present the design section by section (not all at once). Get feedback on each section, incorporate it, then move to the next:

   • Overview and goals
   • Decisions made (with rationale from brainstorming)
   • Technical design (data structures, APIs, file layout)
   • Integration points (entry points, registrations, docs, decisions, knowledge impact)
   • Success criteria (observable, testable outcomes)
   • Implementation order (high-level phases, not detailed tasks)

   The Integration Points section is required in every spec. It defines how the feature connects to the existing system. Populate it with five subsections:

   • Entry Points -- Which system entry points does this feature touch or create? (e.g., new CLI command, new MCP tool, new skill, new API route, new barrel export)
   • Registrations Required -- What registrations are needed for the feature to be discoverable? (e.g., barrel export regeneration, skill tier assignment, route registration)
   • Documentation Updates -- What docs need updating to reflect the new capability? (e.g., AGENTS.md section, API docs, README, guides)
   • Architectural Decisions -- What decisions warrant ADRs? List the decision and a one-line rationale. Only for medium/large tier changes -- omit for small changes.
   • Knowledge Impact -- What domain concepts, patterns, or relationships should enter the knowledge graph?

   If the feature is a small change (bug fix, config tweak, < 3 files), the section may contain only Entry Points and Registrations Required with "None" for the others. The section must still be present.

2. Run soundness review. Invoke harness-soundness-review --mode spec against the draft. Do not write to docs/ until the review converges with no remaining issues.

3. Write the spec to docs/changes/<feature>/proposal.md.

4. Run skill advisor scan. After writing the spec, extract signals from its content and scan the skill index for relevant skills. Write results to docs/changes/<feature>/SKILLS.md alongside the spec.

   Use the advise_skills MCP tool:

   advise_skills({
     "path": "<project-root>",
     "specPath": "docs/changes/<feature>/proposal.md"
   })
   

   Announce findings in a brief summary (skip announcement in --fast mode):

   Skill Advisor: Found N relevant skills for '<feature>'
     Apply: N (skill-a, skill-b, ...)
     Reference: N | Consider: N
     Full list: docs/changes/<feature>/SKILLS.md
   

   In --thorough mode, show the full skill list for human review before proceeding.

5. Run harness validate to verify proper placement and project health.

6. Request sign-off via emit_interaction:

   emit_interaction({
     path: "<project-root>",
     type: "confirmation",
     confirmation: {
       text: "Approve spec at <file-path>?",
       context: "<one-paragraph summary>",
       impact: "Spec approval unlocks implementation planning. No code changes yet.",
       risk: "low"
     }
   })
   

   The human must explicitly approve before this skill is complete.

7. Commit spec artifacts. After approval, commit the spec and skill recommendations so the paper trail enters git history at sign-off rather than retroactively:

   git add docs/changes/<feature>/proposal.md docs/changes/<feature>/SKILLS.md
   git commit -m "docs(<feature>): add spec"
   

   Do not skip this step. harness-execution commits only implementation files, so a spec uncommitted here stays untracked until someone notices. If a pre-commit hook reformats either file, re-add and re-commit.

8. Add feature to roadmap. If docs/roadmap.md exists:

   • Derive feature name from the spec title (the H1 heading).
   • Call manage_roadmap with action add, status: "planned", milestone: "Current Work", and the spec path.
   • If the feature already exists, skip silently.
   • If manage_roadmap is unavailable, fall back to parseRoadmap/serializeRoadmap from core. Warn: "External sync skipped (MCP unavailable). Run manage_roadmap sync when MCP is restored."
   • If no roadmap exists, skip silently.

9. Write handoff and suggest transition. After approval:

   Write handoff to the session-scoped path when a session slug is known, otherwise fall back to the global path:

   • Session-scoped (preferred): .harness/sessions/<session-slug>/handoff.json
   • Global (fallback, deprecated): .harness/handoff.json

   [DEPRECATED] Writing to .harness/handoff.json is deprecated. When running within an autopilot session, always write to .harness/sessions/<session-slug>/handoff.json. Global writes cause cross-session contamination in parallel runs.

   {
     "fromSkill": "harness-brainstorming",
     "phase": "VALIDATE",
     "summary": "<1-sentence summary>",
     "artifacts": ["<spec path>"],
     "decisions": [{ "what": "<decision>", "why": "<rationale>" }],
     "contextKeywords": ["<keywords from Phase 2>"],
     "recommendedSkills": {
       "apply": ["<skill-names>"],
       "reference": ["<skill-names>"],
       "consider": ["<skill-names>"],
       "skillsPath": "docs/changes/<feature>/SKILLS.md"
     }
   }
   

   Call emit_interaction:

   {
     "type": "transition",
     "transition": {
       "completedPhase": "brainstorming",
       "suggestedNext": "planning",
       "reason": "Spec approved and written to docs/",
       "artifacts": ["<spec path>"],
       "requiresConfirmation": true,
       "summary": "<title> -- <key choices>. <N> success criteria, <N> phases.",
       "qualityGate": {
         "checks": [
           {
             "name": "spec-written",
             "passed": true,
             "detail": "Written to docs/changes/<feature>/proposal.md"
           },
           { "name": "harness-validate", "passed": true },
           { "name": "human-approved", "passed": true }
         ],
         "allPassed": true
       }
     }
   }
   

   If confirmed: invoke harness-planning with the spec path. If declined: stop. The handoff is written for future invocation.

---

Scope Check

If the design reveals larger-than-expected scope:

1. Identify natural decomposition boundaries -- where can it split into independent pieces?
2. Propose sub-projects, each brainstormable and plannable on its own.
3. Get approval for decomposition before continuing.

Party Mode

When activated with --party, add multi-perspective evaluation after proposing approaches.

Perspective Selection

Select 2-3 perspectives based on topic:

Topic	Perspectives
API/backend	Backend Developer, API Consumer, Operations
UI/frontend	Developer, Designer, End User
Infra	Architect, SRE, Developer
Data model	Backend Dev, Data Consumer, Migration
Library/SDK	Library Author, Consumer, Maintainer
Cross-cutting	Architect, Security, Developer
Default	Architect, Developer, User/Consumer

Evaluation Process

For each approach, evaluate from each perspective:

### Approach N: [name]
**[Perspective 1]:** [Assessment]. Concern: [specific or "None"].
**[Perspective 2]:** [Assessment]. Concern: [specific or "None"].
**[Perspective 3]:** [Assessment]. Concern: [specific or "None"].
**Synthesis:** [Consensus. Address concerns. Recommend proceed/revise.]

Converge on a recommendation that addresses all concerns before presenting the design.

Session State

Section	R	W	Purpose
terminology	Y	Y	Domain terms discovered during brainstorming
decisions		Y	Design decisions made during exploration
constraints	Y		Reads constraints to scope brainstorming
risks		Y	Risks identified during brainstorming
openQuestions	Y	Y	Adds new questions, resolves answered ones
evidence		Y	Cites sources for recommendations and prior art

Write after each phase transition (EXPLORE->EVALUATE->PRIORITIZE->VALIDATE) so downstream skills inherit context. Read at Phase 1 start -- terminology and constraints from session for prior context.

Evidence Requirements

Technical claims about existing code, architecture, or tradeoffs MUST cite evidence:

1. File reference: file:line (e.g., src/services/auth.ts:42 -- "existing JWT middleware")
2. Prior art: file with description (e.g., src/utils/email.ts -- "reusable for notifications")
3. Docs: docs/path (e.g., docs/changes/user-auth/proposal.md -- "established OAuth2 standard")
4. Strategy grounding: STRATEGY.md with section reference (e.g., STRATEGY.md#tracks -- "advances the 'pulse-reports' track"). Cite when Phase 1 step 0a loaded a valid strategy AND the decision is informed by it. Mandatory when the spec extends, narrows, or contradicts a strategy section.
5. Session evidence: Write via manage_state append_entry to evidence section.

When to cite: Phase 1 (existing code/patterns), Phase 3 (tradeoff justifications), Phase 4 (spec referencing existing implementation).

Uncited claims MUST be prefixed with [UNVERIFIED]. These are flagged during review.

Harness Integration

• harness validate -- Run after writing the spec. Verifies project health and spec placement.
• harness check-docs -- Verify spec does not conflict with existing docs.
• STRATEGY.md grounding (Phase 1 step 0a) -- When present at repo root and valid, loaded via the read_strategy MCP tool (which the harness MCP server backs with validateStrategy + parseStrategyDoc + asStrategyDoc from @harness-engineering/core — projects do not need core installed). Soft-fails when absent or invalid; cites strategy sections in the spec's evidence annotations when present. Boundary with harness-strategy: brainstorming READS; harness-strategy WRITES. Never modify STRATEGY.md from this skill.
• Spec location -- docs/changes/<feature>/proposal.md.
• Handoff -- Once approved, invoke harness-planning to create the implementation plan.
• Session directory — When session slug is known, handoff goes to .harness/sessions/<slug>/handoff.json. The session directory structure is: handoff.json, state.json, artifacts.json (registry of spec/plan paths and file lists). Do not write to .harness/handoff.json in session context.
• Spec commit -- After sign-off (Phase 4 Step 7), commit docs/changes/<feature>/proposal.md and docs/changes/<feature>/SKILLS.md so the spec enters git history at approval, not retroactively. harness-execution does not backfill these — see issue #487.
• Roadmap sync -- After approval, call manage_roadmap action add to register as planned. Skip silently if no roadmap. Duplicates ignored.
• emit_interaction -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).

Requirement Phrasing

When brainstorming produces requirements for planning, prefer EARS sentence patterns (see harness-planning for full reference):

• Event-driven: "When [trigger], the system shall [response]."
• Unwanted: "If [condition], then the system shall not [behavior]."

Apply when output includes specific behavioral expectations.

Success Criteria

• Spec exists in docs/ with all required sections (overview, decisions, technical design, integration points, success criteria, implementation order)
• Human explicitly approved before any implementation
• YAGNI applied: no speculative features in the spec
• 2-3 approaches presented with honest tradeoffs before decision
• Questions asked one at a time with multiple-choice options where possible
• harness validate passes after spec is written
• If scope was too large, it was decomposed with human approval

Rationalizations to Reject

Rationalization	Reality
"I already understand the problem well enough to skip the question phase"	The Gates section is explicit: you must ask at least one clarifying question before proposing approaches. Skipping questions means making untested assumptions.
"There is only one viable approach, so presenting alternatives would be contrived"	The gate requires at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision -- the human has no real choice.
"I will draft the full spec and present it for review all at once to save time"	Section-dump specs are explicitly forbidden. Presenting section by section with feedback between each catches misunderstandings early.
"This future capability is low-cost to include now, so we should build it in"	YAGNI is a gate, not a suggestion. Every capability must trace to a stated requirement. "We might need this later" is the exact rationalization that turns focused specs into bloated ones.

Examples

Example: Designing a Notification System

EXPLORE:

Read AGENTS.md -- TypeScript monorepo, React frontend, Express backend.
No prior notification specs. Found docs/changes/user-auth/proposal.md as naming example.
No notification code in src/services/. Found email utility in src/utils/email.ts.
Scope: single subsystem, ~1 week. Proceed.

EVALUATE:

Q1: "Notifications: (A) Email only, (B) Email + in-app, (C) Email + in-app + push?"
Human: "B -- email and in-app."
Q2: "In-app delivery: (A) Poll every 30s (simple), (B) WebSocket (real-time, more infra)?"
Human: "A -- polling is fine."
Q3: "Store permanently or expire after 30 days?"
Human: "Expire after 30 days."

PRIORITIZE:

Approach 1: Event-driven with queue
- Services emit events, worker consumes and dispatches
- Tradeoff: More infra (needs queue), but decoupled and scalable
- Complexity: Medium. Risk: Queue adds operational overhead

Approach 2: Direct service calls
- Services call NotificationService directly
- Tradeoff: Simpler, but couples services to notification logic
- Complexity: Low. Risk: Harder to add channels later, synchronous blocking

Recommendation: Approach 2 (YAGNI). Direct calls suffice for email + polling.
Human: "Agreed."

VALIDATE:

Wrote docs/changes/notification-system/proposal.md
Sections: Overview, Decisions, Technical Design, Success Criteria, Implementation Order
harness validate -- passes. Human: "Approved."

Gates

These are hard stops. Violating any gate means the process has broken down.

• No implementation before approval. No production code, tests, or scaffolding. The spec must be approved first. If you wrote code, delete it.
• No skipping the question phase. Ask at least one clarifying question before proposing approaches. If you think you know the answer, validate the assumption.
• No single-approach proposals. Always present at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision.
• No speculative features. Every capability must trace to a stated requirement. "We might need this later" is not a requirement.
• No section-dump specs. Present section by section with feedback between each. Do not write the entire spec and ask "looks good?"

Escalation

• Human cannot decide between approaches: Identify the key differentiator. Ask: "The main difference is X. Given your priorities, does X matter more than Y?" If still stuck, suggest a small spike (not production code).
• Scope keeps growing: Stop brainstorming. Say: "Scope has expanded beyond the original problem. Should we (A) decompose into sub-projects, or (B) narrow the original goal?"
• Unfamiliar problem domain: State what you do not know. Ask if the human has domain expertise, docs, or a reference implementation. Do not guess at domain-specific requirements.
• Requirements conflict with architecture: Flag explicitly: "The spec calls for X, but current architecture assumes Y. Should we (A) change the spec, or (B) plan an architecture change as prerequisite?"
• More than 10 questions without converging: The problem is too large or ambiguous. Stop and propose decomposition or a scoping exercise.