write-conceptual

name

write-conceptual

description

Transform technical source material into polished non-technical conceptual writing for non-expert audiences. Use when asked to write a presentation, overview, explainer, or narrative about a technical product or system for potential users, stakeholders, investors, or the general public. Triggers on: "write a presentation about", "non-technical overview", "explain what this does for users", "product narrative", "conceptual overview", "write this for a non-technical audience", "turn this into something readable", or any request to produce reader-facing prose from technical documentation. Also triggers when transforming developer docs, reference specs, or architecture documents into editorial-style writing. Do NOT trigger for technical documentation, API docs, or developer guides -- those need technical precision, not conceptual prose.

Conceptual Writing

Transform technical source material into polished, editorial-quality prose for non-expert audiences through structured collaboration with the user.

This skill is designed for INTERACTIVE, COLLABORATIVE use. Each phase involves user review and correction. User corrections are not bugs -- they are the primary mechanism for quality. Integrate them immediately and completely.

The phases are sequential but the user may jump back to any phase at any time.

When running autonomously (e.g., in a subagent), proceed through all phases making reasonable choices, but note where user input would normally be solicited.

Phase 0: Deep Research

Read ALL source material before writing anything. Reference docs, chat history, prior conversations -- everything available. Use the deep-reading skill if available for complex source documents.

Extract:

• Product vision and core purpose
• Architecture and key concepts
• Organizational structure
• Differentiators
• Audience-relevant features

Do NOT start writing until you have thoroughly read the source material.

Phase 1: Collaborative Structure Proposal

Propose a section structure (typically 4--7 sections) based on the source material. Each section gets a descriptive name -- not a full-sentence header yet (that comes in Phase 2).

Present the structure to the user for iterative refinement: flipping order, merging sections, splitting sections, renaming.

Critical rules for collaborative editing

• Section numbers are STABLE. Once assigned, they do not change. If sections are reordered, the numbers stay with the content they were assigned to.
• "Goes under" means "becomes a subsection of", NOT "repositioned after." Never renumber.
• Disambiguate numbering systems. When multiple numbered lists exist in conversation (e.g., your analysis items 1, 2, 3 AND outline sections 1--6), ALWAYS clarify which numbering system the user is referring to. Never assume.
• Do not add, remove, or reorder sections without explicit user instruction.

Phase 2: Sub-section Development

For each section, develop sub-sections with FULL-SENTENCE HEADERS in active voice.

Good: "The system figures out the right quantity of each thing" Bad: "Quantity Calculation" or "How quantities work"

Headers should make claims, not label topics. A reader skimming only headers should get the argument.

Audit the outline against source material for gaps. Present findings as a numbered list SEPARATE from section numbers.

Phase 3: Expansion Pass

Expand each sub-section's header into a paragraph. This is a single-purpose pass: only expand, do not simplify or restructure.

Each sub-section opens with a bold lead sentence followed by supporting text. The bold lead sentence is the sub-section's core claim. The following text provides mechanism, evidence, or example.

Move between abstraction levels within each sub-section: concept, detail, example -- in any permutation that maintains momentum.

Phase 4: Simplification Pass

Go through systematically examining how each sentence flows into the next. This is a single-purpose pass: only simplify, do not add new content.

• Tighten prose. Remove redundancy. Create movement.
• Replace complex explanations with concrete, human-scale examples.

Bad: "The system computes specific quantities based on how items actually get used, not arbitrary multipliers."

Good: "If two templates both include sunscreen, you get one. If you need a shirt for each day between laundry loads, you get three for a 21-day trip, not twenty-one."

Phase 5: Flow Smoothing

Another pass focused on sentence-to-sentence transitions. Each sentence should flow logically from the previous one. Smooth connections between concept, detail, and example levels. The reader should never feel a jarring shift in register or abstraction level.

Phase 6: Intro and Conclusion

Write LAST, after all body sections are complete.

The introduction grounds the piece in a relatable human experience, not a product description. The conclusion ties back to the opening framing and names the core value proposition.

Neither intro nor conclusion should summarize the sections -- they frame and close the argument.

Anti-Patterns

Framing

• NEVER use defensive framing: "It isn't X" or "Unlike X" as an opener. Be PROACTIVE -- explain what the system IS and why.
• NEVER presuppose knowledge of the product: "it resolves which scaling rule applies" means nothing to someone who hasn't used it. Reword so the behavior is self-evident.
• NEVER frame the product as a category it transcends: if the user corrects your framing, adopt their reframe completely.

Tone and Register

• Confident editorial tone. Declarative statements. No hedging ("might", "could potentially", "it's worth noting").
• No sales language. No calls to action. No "imagine if" scenarios. No exclamation marks.
• No jargon without explanation. Technical terms that the audience would not know must be explained in context or replaced.
• Adopt the user's specific phrasings when they correct your wording. Their voice matters.

Lists

Lists are a technical documentation pattern. Conceptual writing flows as PROSE.

• NEVER use bullet lists or numbered lists in the output document.
• The only acceptable list-like structure is a series of bold-lead paragraphs under a section header.
• Test: "would a magazine editor leave this list in, or convert it to prose?" If the latter, write prose.
• Exception: if a list contains concrete, human-scale items the reader can picture (like specific gear items or specific activities), it may work. Feature inventories, capability enumerations, and technical specs never work as lists.

Structure

• Two heading levels maximum: ## for sections, ### for sub-sections.
• Horizontal rules (---) between major sections for visual breathing room.
• Every sub-section opens with a bold lead sentence.
• The piece should be scannable: reading only headers and bold leads should convey the complete argument.