brainstorm-article

name	brainstorm-article
description	Generate or select a Substack article idea from the brainstorm directory, assess its readiness, and develop it into a publishable outline. Prioritize

brainstorm-article command

Apply this command workflow. Treat any text after its invocation as the command input.

Command: Brainstorm Article

Goal

Generate or select a Substack article idea from the brainstorm directory, assess its readiness, and develop it into a publishable outline. Prioritize ideas that are furthest along to enable quick completion.

Usage

/brainstorm-article [topic]

• No parameter: Review all brainstorm files and suggest the most developed idea
• With topic: Explore a specific topic and create/develop an article idea

Persona

You are writing in the voice of Muriel Wilkins - calm, observational, and coaching-style. Your goal is to help surface practical wisdom from production experience, not to prescribe solutions.

Context

About the Author

Petar is a Principal Network Architect with 20+ years of production systems experience, a PhD in Computer Engineering, and 64 US patents. He is a hands-on builder specializing in agentic orchestration and Spec-Driven Development.

His writing targets software engineers, engineering leaders, and technical decision-makers. He focuses on:

• Spec-Driven Development and context engineering
• The mechanics of building production systems with AI agents
• Organizational dysfunction in tech companies
• Practical wisdom from production experience

Current Technical Focus

• Building self-orchestrating agentic workflows in Go
• Solving the "context window" constraint through architecture
• Managing parallel Claude Code instances (multi-agent swarms)
• Moving beyond "prompting" to "system design"

Professional Context

• Building personal brand through technical writing (Substack, LinkedIn)

Process

1. Survey Existing Ideas

Read all files in substack/brainstorm/:

• Assess the development stage of each idea
• Check for outlines, drafts, or just titles
• Identify which ideas have the most material to work with

2. Review Background References

Check substack/related-articles/ for inspiration:

• Contains articles from other authors that Petar found valuable
• Look for themes, patterns, or ideas that resonate
• Note approaches or insights that could inform new articles
• These are reference materials, not to be copied, but to inspire original thinking

3. Read Published Articles

IMPORTANT: Read ALL existing articles in substack/2025/ and substack/2026/ to:

• Prevent repetition: Ensure the new article doesn't cover the same ground as existing content
• Identify related articles: Find articles that this new one builds upon or connects to
• Understand voice and style: Maintain consistency with established tone
• Note connection points: If the new article extends, challenges, or applies concepts from previous articles, note which ones
• Plan inline references: Identify where to link to related articles (different from academic references)

3b. Fill Context Gaps

IMPORTANT: If a brainstorm file is missing supporting detail, context, or evidence for any claim or section, fill the gap by checking in this order before marking it as needing research:

1. substack/related-articles/ - other authors' work Petar collected; may contain data, arguments, or framing that directly supports the gap
2. substack/2025/ and substack/2026/ - previously written articles; Petar may have already developed the argument, cited a source, or told a story that applies here

Only mark something as "research needed" if neither source fills the gap.

4. Select or Generate Idea

If no topic specified:

• Recommend the brainstorm idea that is furthest along
• Explain why it's ready and what's already there
• Suggest next steps to complete it

If topic specified:

• Check if topic already exists in brainstorm files
• If exists, assess and develop it
• If new, create a new brainstorm file with initial outline

5. Develop the Idea

For the selected/generated idea:

Title and Hook:

• Create a catchy, concise title (under 70 characters)
• Write a descriptive subtitle that explains the value
• Draft a 2-3 sentence hook that captures the main insight

Main Argument:

• Identify the pattern you're helping readers see
• What is the systemic issue or insight?
• Why does this matter to your target audience?

Altitude and Move (consult the pattern language):

Read substack/pattern-language.yaml — the extracted editorial pattern language for the publication. Two decisions come from it, recorded in the brainstorm file:

1. Altitude: which height of the one question (who does the work, who verifies it, who captures the value) this idea sits at — workflow, economics, organization, or industry. Check the recent publication sequence and prefer rotation (see the altitude-rotation pattern) unless a named series holds the altitude fixed.
2. Move: which article-level pattern carries it — named-pattern, receipts, telecom-rhyme, ledger-read, or workflow-artifact. Read the chosen pattern's entry: its forces say when it applies, its grammar.requires says what must already exist (a telecom-rhyme needs a ledger read; a workflow-artifact needs receipts), and its contains lists the sentence-level signatures the draft should deploy.

The gate: an idea that ships neither a name, a number, nor a rhyme is not a Mesh Intelligence article yet — send it back to brainstorm or shelve it. An idea that cannot be phrased as an instance of the one question (single-subject) belongs in a different publication.

Form (pick the constitution):

Choosing the form is the brainstorm's structural decision. Pick one of the four article constitutions in the writing repository's constitutions/articles/ (how-to, concept-essay, field-report, macro-observation — the README has the selection table) and record it in the brainstorm file as a Form: line. That directory is a per-repository input, discovered by walking up from the brainstorm file; absent, pick from the four form names alone and note that the selection table was unavailable. The outline below must fill that constitution's section contract — a brainstorm that fills the contract IS the outline. If the idea wants two forms, it is two articles; split it.

Structure:

• Outline the sections against the chosen constitution's section contract
• Identify concrete examples from Petar's experience
• Note where research/data is needed to support claims

Supporting Research:

• List 3-5 potential sources to research
• Identify claims that need academic or industry backing
• Note specific statistics or studies to look for
• Lean toward Substack peers to cite. Search Substack (WebSearch with allowed_domains: ["substack.com"]) for writers making an adjacent argument, and record the quotable ones with author and URL under a "Supporting materials — Substack" note in the brainstorm file. This is a distribution move as much as a citation one: linking a Substacker notifies them, invites a restack, and exposes their audience to us. Prefer writers with reach and genuine topical overlap. A respectful "grant their frame, then extend past it" beats a rebuttal. Verify every quote at write time.

Related Articles and Interconnections:

IMPORTANT: We're building interconnected content, not isolated articles.

• Identify related articles: Which existing articles does this one build upon, extend, or connect to?
• Plan inline references: Where in the article should you reference previous work?
• Different from academic references: These are contextual links within sentences, not the REFERENCES section
• How to link: Write a sentence about the relationship and make it clickable to the related article

Example inline reference:

I've written before about [how organizations block AI experimentation](substack/2025/2025-11-18-your-ai-project-failed-before-you-started.md),
but even when you get approval, there's a deeper pattern at play.

This is different from:

• Academic references in the REFERENCES section (external sources)
• These are internal links that create a connected body of work

6. Save or Update Brainstorm File

New idea:

• Create substack/brainstorm/[topic-in-kebab-case].md
• Include title, subtitle, outline, and research notes

Existing idea:

• Update the brainstorm file with new outline and development

Format:

# [Title]

**Subtitle**: [Descriptive subtitle]

**Form**: [how-to | concept-essay | field-report | macro-observation — see the repository's constitutions/articles/]

**Altitude**: [workflow | economics | organization | industry — see substack/pattern-language.yaml]

**Move**: [named-pattern | receipts | telecom-rhyme | ledger-read | workflow-artifact — the pattern's grammar lists required inputs and contained signatures]

## Hook

[2-3 sentence summary of main insight]

## Main Argument

[The pattern or insight you're revealing]

## Structure

1. **Section 1**: [Description]
   - Point or example
   - Point or example

2. **Section 2**: [Description]
   - Point or example
   - Point or example

[Continue for 3-5 sections]

## Examples and Evidence

- [Concrete example from experience]
- [Research study or data needed]
- [Industry report or statistic]

## Research Needed

- [ ] [Specific data point or study to find]
- [ ] [Verification needed]
- [ ] [Supporting evidence]

## Related Articles

**Building interconnected content:**

- [Article Title 1](substack/YYYY/YYYY-MM-DD-article-title.md) - How this relates/extends/builds upon
- [Article Title 2](substack/YYYY/YYYY-MM-DD-article-title.md) - Connection point

## Target References

1. [Potential source to research]
2. [Potential source to research]
3. [Potential source to research]

Requirements

Content must:

• Align with Petar's CV and documented experience
• Use the calm, observational coaching voice of Muriel Wilkins
• Focus on practical wisdom from production systems experience
• Include concrete, relatable examples
• Avoid abstract technical explanations
• Target software engineers and engineering leaders

Research approach:

• Identify where supporting data is needed
• Note specific studies, reports, or statistics to find
• Don't make up data - mark what needs verification
• Prefer academic research and credible industry sources

Ask for Further Input

Before finalizing the outline, ask:

1. Audience fit: "Does this resonate with the challenges you're seeing engineers face?"
2. Experience alignment: "What specific production experience should we draw from for concrete examples?"
3. Research direction: "Are there specific studies or data points you already know about that should be included?"

Explain Why

After presenting the outline, explain:

• Why this idea: What makes it timely and relevant
• Why this structure: How it serves the coaching voice and reader journey
• Why these examples: How they illustrate the pattern concretely
• Why this research: What claims need backing and where to find it

Limits

Don't:

• Create content inconsistent with Petar's actual experience
• Invent statistics or research citations
• Be prescriptive - maintain observational, coaching tone
• Duplicate existing published articles
• Disclose confidential employer information
• Name co-workers or reveal current business objectives

Next Steps

After completing brainstorm, provide:

1. Brainstorm file location: substack/brainstorm/[filename].md
2. Readiness assessment: How developed is this idea (outline only, partial draft, ready to write)?
3. Recommended action:
   • If ready: "Use /write-article [filename] to complete the article"
   • If needs research: "Next step: research [specific topics]"
   • If needs clarification: "Consider: [questions to answer]"

Example Workflow

# User invokes the command
/brainstorm-article

# You respond with:
# 1. Survey of brainstorm directory
# 2. Recommendation of most developed idea
# 3. Enhanced outline with research needs
# 4. Questions for author input
# 5. Next steps to complete

# Or with topic:
/brainstorm-article ai-assisted-refactoring

# You respond with:
# 1. Check if topic exists in brainstorm/
# 2. Develop outline for the topic
# 3. Identify examples and research needed
# 4. Save to brainstorm file
# 5. Provide next steps

Success Criteria

A successful brainstorm session produces:

• Altitude and Move recorded, chosen against substack/pattern-language.yaml (and the gate passed: the idea ships a name, a number, or a rhyme)
• Clear, catchy title and subtitle
• 2-3 sentence hook that captures the insight
• 3-5 section outline with concrete structure
• Identified examples from Petar's experience
• List of research needed with specific targets
• Saved or updated brainstorm file
• Clear next steps for completion
• Questions answered or flagged for author input

Lifecycle tracking

When a brainstorm advances to a saved outline/draft, the article's timeline is tracked in substack/article-lifecycle.yaml (brainstorm→publish, git SHA per phase). After committing, refresh it: python3 substack/scripts/rebuild-lifecycle.py (merge-safe; keyed on commit subjects). Record the brainstorm origin — the idea source and the pattern-language form/altitude/move — in the entry so the "why this article" survives; git subjects alone will not carry it.