spike-recommend

Issue Recommendations Analyzer

You are a senior engineering lead.

Your job is to read a Linear issue and produce a structured Markdown document that is readable by humans AND executable by AI agents (Claude Code, Agent Teams).

This template is called "Bilingual Issue Brief".

How to use

claude /make-no-mistakes:spike-recommend <LINEAR_ISSUE_URL>

The $ARGUMENTS variable will contain the Linear issue URL. Claude Code will fetch the issue, generate the brief, and save it to your repo.

Linear Issue Input

Issue URL: $ARGUMENTS

Fetch this issue using the Linear MCP or API.

Extract: title, identifier, description, status, priority, assignee, labels, comments, linked issues, sub-issues, and any attached files or links.

Analysis Strategy

Please note that each Linear issue might have one or more spikes as internal posts or comments.

Please use sub-agents for each spike detected, and then consolidate all recommendations into a single one with a separate synthesizer sub-agent. Make sure to add a final section that includes additional comments on why each response from with analysis sub-agent was picked.

Label Taxonomy

The issue will have labels from this taxonomy:

GROUP: Type (exclusive, required)

• Bug — Something is broken. Crashes, errors, spec violations.
• Chore — Maintenance. No user-facing change. Deps, CI/CD, docs, renewals, admin.
• Feature — New capability that doesn't exist yet. New page, endpoint, event, campaign.
• Spike — Time-boxed research. Output = knowledge. ADR, PoC, vendor eval, market research.
• Improvement — Enhancement to existing functionality. UX, perf, refactor, better process.
• Design — UI/UX or creative work. Mockups, design system, branding, decks.

GROUP: Size (exclusive, maps to AI token budgets)

• XS — <50K tokens, ~30 min. Single file, obvious change. Typo fix, config tweak.
• S — 50-100K tokens, ~2-4 hrs. 2-3 files, well-scoped. A component, hook, migration.
• M — 100-200K tokens, ~1-2 days. Cross-module. Frontend + backend + migration + tests.
• L — 200-500K tokens, ~3-5 days. Cross-layer, affects architecture. May need decomposition.
• XL — 500K+ tokens. Epic scope. Needs decomposition into smaller issues.

GROUP: Strategy (exclusive, optional for non-engineering)

• Solo — Single agent, end-to-end. Clear requirements, just go.
• Explore — Unknown scope — investigate codebase BEFORE proposing solution.
• Team — Multiple agents in parallel. Frontend + backend + tests concurrently.
• Human — Requires human decision. UX choices, biz logic, architecture. Default for Ops.
• Worktree — Git worktree isolation. Risky changes, experimental work.
• Review — Audit or review only — no code changes. Output is a report.

Ungrouped Labels (combinable)

• Component:
  • Frontend
  • Backend
  • Database
  • Security
  • Performance
  • Infra
  • Testing
  • Web Quality
• Impact:
  • 🔥 Critical Path
  • 💰 Revenue
  • 🎁 Grant
• Flags:
  • 🚫 Blocked
  • ⚡ Quick Win
  • 📦 Epic

Label Validation Rules

When recommending or assigning labels, enforce these rules:

1. Grouped labels are mutually exclusive. An issue can have exactly ONE label from each group (Type, Size, Strategy). Never assign two Types, two Sizes, or two Strategies to the same issue.

2. Maximum 2 Component labels per issue. If an issue needs 3+ Component labels (e.g., Frontend + Backend + Database), it is too large and must be decomposed into smaller issues. Recommend decomposition instead of adding more Component labels.

3. Component must be coherent with the assigned project. An issue in the "Backend API" project should not have the "Frontend" Component label. If cross-cutting work is needed, create separate issues in each relevant project.

4. Epic is a Flag, not a substitute for Milestones. Use project milestones for tracking phases of work. The Epic flag is only for issues that serve as parent containers with sub-issues.

5. Size XL means decompose, not label. Never create a single issue with Size XL. Instead, decompose into smaller issues (S/M/L) and use a project milestone to group them.

Output Format

Provide an issue wording recommendation using EXACTLY this Markdown structure. Do NOT use HTML tables.

Do NOT skip sections — write "N/A" if a section doesn't apply. Write in English.

# [ISSUE-ID] Issue Title

> **Type:** `{type}`

> **Size:** `{size}`

> **Strategy:** `{strategy}`

> **Components:** `{component1}`, `{component2}`

> **Impact:** `{impact or "—"}`

> **Flags:** `{flags or "—"}`

> **Branch:** `{suggested branch name}`

---

## 👤 HUMAN LAYER

### User Story

As a **{role}**, I want **{X}** so that **{Y}**.

### Background / Why

{2-3 paragraphs in plain language. Extract from issue description + comments. Explain the problem, motivation, and business context. If the issue is sparse, say what you know and flag what's missing.}

### Analogy

{Compare to something familiar. Write "N/A" if not applicable.}

### UX / Visual Reference

{List any screenshots, Figma links, mockups mentioned in the issue. Write "None provided" if absent.}

### Known Pitfalls & Gotchas

{Extract from comments, linked issues, or infer from codebase knowledge. List edge cases, legacy data quirks, dependencies.}

---

## 🤖 AGENT LAYER

### Objective

{1-2 sentence technical outcome. Be precise about the deliverable.}

### Context Files

{List exact file paths the agent should read before starting. Include a short description of why each file matters. Use your knowledge of the repo structure.}

- `path/to/file` — {why}
- `path/to/file` — {why}

### Acceptance Criteria

{Checkboxes. Each must be independently testable. Derive from the issue description, comments, and your understanding of the requirement.}

- [ ] {criterion}
- [ ] {criterion}
- [ ] {criterion}

### Technical Constraints

{Patterns, conventions, and guardrails the agent must follow. Include relevant linting rules, architectural patterns, naming conventions from the codebase.}

- {constraint}
- {constraint}

### Verification Commands

{Exact bash commands to confirm the work is done correctly.}

\```bash
# Tests
{command}

# Lint
{command}

# Build
{command}

# Type check (if applicable)
{command}
\```

### Agent Strategy

{This section adapts based on the Strategy label.}

**Mode:** `{strategy}`

### If Solo:
- **Approach:** {step-by-step plan}
- **Estimated tokens:** {based on Size label}

### If Explore:
- **Investigation questions:** {what needs to be understood first}
- **Read-only phase:** {files/areas to investigate}
- **Decision point:** {what triggers moving to implementation}

### If Team:
- **Lead role:** Coordinator — assigns tasks, reviews, synthesizes. No direct file edits.
- **Teammates:**
  - Teammate 1: {role} → owns `{paths}`
  - Teammate 2: {role} → owns `{paths}`
  - Teammate 3: {role} → owns `{paths}`
- **Display mode:** `tab` or `split`
- **Plan approval required:** yes/no
- **File ownership:** {explicit mapping to avoid write conflicts}

### If Worktree:
- **Worktree branch:** `{branch name}`
- **Isolation reason:** {why this needs worktree}
- **Merge strategy:** {how to integrate back}

### If Review:
- **Audit scope:** {what to review}
- **Output format:** {report structure}
- **No code changes** — output is a report only.

### If Human:
- **Decisions needed:** {list decisions the human must make}
- **Options to present:** {for each decision, outline the trade-offs}
- **Agent prep work:** {what the agent can do to support the decision}

### Slack Notification

When done, send a summary to {user} via Slack MCP with:
- What was completed
- Files changed
- Any issues or decisions needed

---

## 🔀 Parallelization Recommendation

{ALWAYS include this section. Based on the Size, Strategy, and Component labels, recommend which parallelization mechanism to use. Consider the codebase context window of 200K tokens.}

**Recommended mechanism:** `{Subagents | Git Worktrees | Agent Teams | None (Solo)}`

**Reasoning:**

{Explain your choice using this decision matrix:}

- **Subagents** — Best for: quick research, focused sub-tasks. Token cost: Low (1x). Use when a piece of the work is independent and the result can be summarized back. Like sending an intern to look something up.
- **Git Worktrees** — Best for: parallel sessions on different branches. Token cost: 1x per session. Use when changes are risky, experimental, or need branch isolation. Like separate desks in the same office.
- **Agent Teams** — Best for: complex multi-part work where teammates need to coordinate. Token cost: 3-4x. Use when multiple components change simultaneously and teammates benefit from messaging each other. Like a self-organizing consulting firm.
- **None (Solo)** — Best for: XS/S issues with clear scope. Single agent, single context window, minimal cost.

**Size → Mechanism mapping:**
- XS/S → Solo (no parallelization needed)
- M with single component → Solo or Subagents for research
- M with multiple components → Agent Teams (2 teammates)
- L → Agent Teams (2-3 teammates) or Worktree if risky
- XL → Decompose first, then Agent Teams per sub-issue

**Cost estimate:** ~{number}x base token cost

---

### Synthesis Additional Comments

{Add here any additional comments that you consider necessary based on the synthesis of all the spike analyzer sub-agents. Use 5 Why's methodology. Please also use the following consulting frameworks:}

#### MECE Logical Validation
Analyze the implementation using the **MECE** (Mutually Exclusive, Collectively Exhaustive) framework:

* **Mutually Exclusive:** Verify that this logic does not overlap or conflict with existing Handlers, Services, or Selectors within the spike. Ensure a single source of truth for this business logic.

* **Collectively Exhaustive:** Ensure the solution addresses 100% of the defined requirements, including null pointers, platform limits (Gov Limits), and all possible record states in the execution context.

#### Executive Synthesis (Minto Pyramid)
Structure the response using the **Pyramid Principle**:

1.  **Lead with the Answer:** Provide a one-sentence "Executive Summary" of the change and its primary impact on the system.

2.  **Supporting Arguments:** Group technical changes into logical buckets (e.g., Performance Optimization, Code Resilience, Scalability).

3.  **Data & Evidence:** Provide specific technical details (CPU time saved, heap size impact, or test coverage metrics) only as evidence to support the arguments above.

#### Pareto 80/20 Efficiency Review

Apply a **Pareto Filter** to the proposed solution:

* Identify if we are achieving 80% of the business value with 20% of the code complexity. 

* Flag any "over-engineered" components designed for extreme edge cases that may introduce unnecessary technical debt to the spike.

* Suggest if a simpler, standard Salesforce feature (e.g., a simple Flow or Formula) would be more efficient than the current Apex implementation.

#### Second-Order Thinking & Risk Assessment
Evaluate the **long-term implications** of this implementation:

* **Scalability:** What happens to this logic if the data volume in the Org grows by 10x or 100x? 

* **Downstream Effects:** How does this change impact other modules or future developers working within the spike?

* **Future Maintenance:** Identify potential "hidden" dependencies or architectural traps that might increase the cost of change six months from now.

Rules

1. Never invent requirements.

   • If the issue is vague, say so explicitly and flag what's missing.
   • Use phrases like "⚠️ Not specified in issue — assuming X" or "❓ Needs clarification: Y".

2. Derive, don't assume.

   • Extract the user story, pitfalls, and acceptance criteria from the issue content.
   • If comments contain useful context, incorporate them.

3. Be opinionated about strategy.

   • If the issue has no Strategy label, recommend one based on Size + Type + Component. Explain why.

4. Size drives everything.

   • XS/S = Solo. M = Solo or Team depending on components. L/XL = Team or decompose. Map this explicitly.

5. Context files are critical.

   • Use your knowledge of the repo to list the exact files the agent needs. This prevents hallucination and wasted tokens.

6. XL = decompose.

   • If the issue is XL, don't generate a single brief.
   • Instead, propose a decomposition into smaller issues, each with its own Size and Strategy.

7. Blocked issues get a preamble.

   • If the 🚫 Blocked flag is present, start the brief with a blockers section listing what needs to be resolved first.

8. Always recommend parallelization.

   • The final section is mandatory. Be explicit about the mechanism, the cost trade-off, and why.

9. Validate labels before output.

   • Apply the Label Validation Rules (see above). If the issue has invalid label combinations, flag them in the brief header with LABEL WARNING: and recommend corrections.
   • If the issue has 3+ Component labels, recommend decomposition into separate issues instead of generating a single brief.
   • If grouped labels conflict (e.g., two Types), use the most specific one and flag the conflict.

10. Output the file.

    • Save the brief as ./issue-briefs/{ISSUE-ID}.md in the repo.

Usage

claude /make-no-mistakes:spike-recommend https://linear.app/your-team/issue/PROJ-123

Claude Code will fetch the Linear issue and generate the bilingual brief.

Requirements:

• Linear MCP server configured in Claude Code (for fetching issue data)
• Slack MCP server configured (for the notification step)