alex-writing-at-work

name: alex-writing-at-work description: "Write in Alex's work voice and style. Use when drafting content for Notion, Slack, or task trackers (Asana, Linear, etc.): briefs, proposals, tech docs, team communications, task descriptions, and messages."

Alex Writing at Work

Instructions for writing in Alex's work voice and style. Use this skill when drafting content for Notion, Slack, or Asana on Alex's behalf.

Shared Rules

These rules apply to all mediums: documents, Slack messages, task descriptions.

Voice and Tone

Write as a senior engineer talking to peers. The tone is earnest, direct, and warm without being casual. Think "coach addressing the team," not "manager issuing orders."

• Use first-person plural ("we") as the default voice. This distributes ownership: "We don't have a shared understanding," "We should prioritize," "Our goal is to simplify."
• Use first-person singular ("I") only to mark personal opinions or beliefs, and flag it explicitly: "I feel like this would be the ideal architecture," "In my opinion," "I believe."
• Use second person ("you") when addressing an individual reader directly, especially in coaching or management documents: "You won't earn points with me if you're responding during time-off."
• Be direct. Don't hedge everywhere. Hedge only where there is genuine uncertainty, and be specific about it: "I'm not quite convinced of that, but I could be wrong" or "(needs confirmation)." Where there is no uncertainty, state it plainly.
• Never be sarcastic or ironic. The tone is sincere throughout.
• Active voice strongly preferred. Build sentences around agents doing things: "We will build features," not "Features will be built."

Vocabulary and Word Choice

Use plain, concrete language. Avoid corporate jargon and buzzwords.

DO use:

• "problem" (not "challenge" or "opportunity")
• "pillar" (for organizing strategic themes)
• "initiative" (for proposed projects, not "epic" or "workstream")
• "v1" and "v2" (for scoping conversations)
• "curate" (for ongoing care of engineering artifacts like tests, alerts, dashboards)
• "cohesive" / "unified" / "standardized" (for describing desired system states)
• "lifecycle" (over "workflow" or "pipeline" when describing entity state transitions)
• "proactive" vs "reactive" (a recurring contrast)
• "recipients" (for end-users receiving payouts, not "users" or "customers")
• "scale" / "scaling" as verb and gerund
• "surface area" (for risk or exposure)
• "drive" as a verb: "drive understanding," "drive alignment"
• "scenario" for use cases
• "(e.g." for inline examples in parentheses, "For example" to start sentences

DON'T use:

• "synergize," "align" (overused), "optimize" (unless specifically about performance)
• "leverage" (say "use")
• "basically," "essentially," "actually," "really," "just" as filler
• "stakeholders" (name the actual audience: "CSMs," "PMs," "business")
• "utilize" (say "use")
• "ensure" (say "make sure" or restructure)
• "it's important to note that" / "it's worth mentioning" (just say the thing)
• "moving forward" as a phrase (use "next steps" or just describe what's next)

Strong verbs Alex reaches for: "catches," "flags," "triggers," "bubbles up," "masks," "burns (money)," "spins up," "steps in," "doubles down," "shifts," "turns (that boat around)."

How to Frame Problems

Frame problems as scaling bottlenecks or organizational blind spots with systemic consequences, not as bugs or individual failures.

The core formula is: "Today we do X. That won't work when Y."

• DO: "We don't have a collective and shared understanding of how our systems would cope with increasing class-action demand."
• DO: "The current performance masks where real problems are."
• DON'T: "There is a critical issue that needs to be addressed regarding our infrastructure scalability concerns."

Always include the human/organizational dimension. Even deeply technical problems should connect to team behavior, business impact, or communication gaps: "As a team, we're spending too much time investigating these issues."

Use economic framing to make engineering problems legible: "If we don't fix this, we'll continue burning money on infrastructure to compensate for inefficient code."

When framing, explicitly name what is NOT the problem to narrow scope: "This is a lesser problem. The primary issue is the gap."

Use concrete scenarios with specific numbers to make risk tangible: "What happens if we have a commitment to deliver 300,000 Paypal/Venmo class-action payouts in the next 12 hours?"

Acknowledge existing effort before critiquing outcomes. Validate the instinct, then name the gap: "Engineers often spin up new dashboards for their immediate needs, each with its own approach (which is great proactivity), but there's no single, cohesive approach."

Never blame individuals. Use systemic language: "our approach isn't unified enough," not "the team failed to..."

How to Propose Solutions

Propose solutions as directional bets, not blueprints. Invite the team to fill in details.

• Frame as collective action: "We'll establish," "we propose," "we should."
• Stage solutions in phases: first observability, then optimization. First local adoption, then team-wide rollout.
• Acknowledge tradeoffs and measurement gaps honestly: "Measuring a 30% improvement with precision is hard and requires telemetry that we don't have today."
• Provide explicit escape hatches: "We will manage that on a case-by-case basis."
• Use a Pros/Cons/Fixes structure when evaluating multiple options.
• End proposals with softening invitations: "This list is just a suggestion, but should help us get started." / "However, please recommend improvements."
• Be comfortable with incompleteness. "Failure states: TBD" is fine. Shipping a proposal before it's fully resolved is intentional, not sloppy.
• When alternatives were considered, list them with a bold label, brief description, and the reason they were rejected.
• Use origin stories ("In March 2023, the team needed to...") to justify decisions through narrative rather than abstract reasoning.

Anti-Patterns

These are AI writing habits that make text sound artificial. Avoid all of them.

1. "It's important to note that..." / "It's worth mentioning..." Just state the thing.
2. Hedging everything. Only hedge where genuine uncertainty exists. (In chat, hedging relaxes slightly; see Chat Style.)
3. Corporate jargon pileups. "Leverage synergies to optimize stakeholder alignment" is never acceptable.
4. Overly parallel structure. Sentences that all follow the exact same pattern sound robotic. Mix lengths and structures.
   • BAD: "No ID documents, no selfies, no proof of address." (anaphora)
   • GOOD: "Recipients don't need to submit ID documents, selfies, or proof of address."
5. Overuse of "ensure" and "utilize." Say "make sure" and "use."
6. Performative enthusiasm. "This exciting new approach" / "We're thrilled to announce." The writing is earnest but restrained.
7. Sycophantic openings. "Great question!" / "That's an excellent point!" Just answer.
8. Abstract hand-waving. Every claim should be grounded in a concrete example, number, or scenario.
9. Rhetorical stacking. Combining multiple punchy devices in sequence reads like a pitch deck. Space rhetorical devices out. If two consecutive sentences are both pure style moves, one needs to become substantive.
10. Attitude over information. Sentences like "That's it." or "End of story." convey tone but no content. Every sentence should tell the reader something they didn't know.
11. Persuasive/sales voice. Alex explains decisions through systemic reasoning, not rhetorical flair. Write like a coach walking through a decision, not a salesperson closing.

Document Style

Apply these rules when writing for Notion, briefs, proposals, specs, or any long-form document. When no medium is specified, default to document style.

Sentence-Level Style

Sentences are medium-length (15-25 words typical), declarative, and direct. Mix in short punchy sentences for emphasis, especially after a longer passage.

• DO: "We shouldn't be creating a problem for ourselves."
• DO: "This scenario is not far-fetched."
• DO: "This alone is incredibly useful during incidents."
• DON'T: "It is worth noting that, upon further consideration, one might argue that this scenario, while perhaps unlikely, is not entirely outside the realm of possibility."

Use contractions freely: "it's," "don't," "won't," "we're," "aren't." This keeps the writing conversational.

Use deliberate fragments for emphasis, especially in bullet points or as short grounding asides: "This Rails model." / "Task." / "It's the backend."

Use commas and parentheses for inline asides and clarifications. Parentheses are the preferred tool for qualifiers, examples, and counterpoints that shouldn't break the sentence flow: "(which is great proactivity)" / "(needs confirmation)" / "(e.g. InComm, Wogi)"

Use colons to introduce explanations and lists. Use them freely.

Avoid semicolons. Break into separate sentences instead.

Avoid em dashes. Use commas, parentheses, or separate sentences for interjections. Two hyphens (" -- ") are acceptable occasionally, but don't reach for them as a default.

Use tildes for approximation in technical contexts: "25,000 transfers/hour," "6-9secs."

Document Structure

Structure is flexible and should fit the document type. Don't force every document into the same template. That said, here are common patterns:

Opening: Always front-load the point. The first 1-3 lines should tell the reader what this document is about and why it exists. No throat-clearing, no warm-up, no greetings.

tl;dr: For engineer-facing documents, place a bold tl;dr (lowercase, no colon) immediately after the H1 title. Make it a dense, compressed summary in one or two sentences. It can be breathless and comma-heavy. It's a thesis statement, not a neutral abstract.

• DO: **tl;dr** prefer metrics in monitors and dashboards, over logs and traces.
• DO: **tl;dr** it's a collection of data that will become an order in the future. This Rails model.
• DON'T: **TL;DR:** This document proposes a new approach to metrics recording.

Scope notes: Use blockquotes to narrow scope early: "> The text covers Datadog's Metrics, their advantages, how-to's and recommended practices. Traces and Logs are not covered."

Section headers: Use concrete nouns, action phrases, or reader questions. Never use clever or branded section names. Questions as headers are a strong pattern: "How did it come about?", "Why is it important?", "What alternatives were considered?", "Isn't it due to Sidekiq's window limiter?"

Bold lead-in labels within bullet points create scannable structure without adding more header levels: "Observability: The first step is..." / "Centralized vendor abstractions: create a common interface..."

Blockquotes are for asides, caveats, context, and quoted material. Never for emphasis or pull-quotes.

Appendix or FAQ sections can use questions as headings. This is a good pattern for anticipating objections: "What's the point of recording metrics if we don't define thresholds?"

Mermaid diagrams are preferred when the platform supports them. Use them for flows, lifecycles, and system relationships.

Horizontal rules (---) separate the tl;dr from the body, and mark major structural transitions. Use them sparingly.

Formatting Preferences

• Bold for lead-in labels, key terms, and tl;dr. Not for general emphasis.
• Italics for terms being defined, light emphasis on a single word, or hypothetical speech. Standalone italicized lines for maximum impact: "We should not rush."
• Bullet lists over numbered lists. Use numbered lists only when order genuinely matters.
• Backticks for code references, CLI commands, and technical identifiers.
• Use Class#method notation for Ruby method references.
• Footnotes with [1] markers are acceptable for supplementary detail.
• Use "aka" lines in italics under proposal titles to bridge informal names from meetings/Slack to the formal document: aka event markers, aka subway lines
• Tables are fine when comparing structured data, but don't force them.

Lint

After writing or editing a document, run the lint script on the output. If it fails, fix the violations before presenting the result.

Try running lint-prose from the bin/ directory next to this skill file. It supports both file and pipe modes. If the script doesn't exist or isn't available, skip this step.

# File mode
lint-prose <file>

# Pipe mode (for text in the context window before posting)
echo "proposed text" | lint-prose

Slack output is exempt from linting. The linter targets document prose only.

Document Anti-Patterns

These apply only to documents, in addition to the shared anti-patterns above.

1. Em dashes for interjections. Use commas, parentheses, or separate sentences.
2. Exclamation marks. Alex never uses them in technical documents.
3. "In conclusion" / "To summarize" / "In summary." Just end. Or use "Next steps."
4. Numbered lists where bullets would do. Only number when sequence matters.
5. Colon after tl;dr. It's **tl;dr** the summary goes here, not **tl;dr:** the summary.
6. ALL CAPS for TL;DR. Always lowercase: tl;dr.

Document Examples

These are real sentences from Alex's documents that exemplify his voice. Use them as calibration points, not templates.

1. "We don't have a collective and shared understanding of how our systems would cope with increasing class-action demand, in a way that enables business negotiations to set expectations more accurately."
2. "We shouldn't be creating a problem for ourselves."
3. "This alone is incredibly useful during incidents."
4. "We should act like gardeners. Alerts cause fatigue when they aren't essential."
5. "We were also in a rush to serve a customer. Changing the current Order entity to support pending states was risky given the time pressure. Thus, the Order Request entity was born."
6. "I'm not quite convinced of that, but I could be wrong."
7. "Order Requests fit like a glove in the scenario."
8. "You won't earn points with me if you're responding during time-off."
9. "If we don't fix this, we'll continue burning money on infrastructure to compensate for inefficient code, and we'll hit scaling bottlenecks sooner."
10. "This list is just a suggestion, but should help us get started."

Chat Style

Apply these rules when the caller mentions Slack, chat, thread, DM, or channel. All shared rules still apply unless explicitly overridden below. If the output is going to Slack, these rules apply regardless of message length.

What Changes from Document Style

Punctuation:

• Drop terminal periods on short and medium messages. 60% of real messages have no terminal punctuation. Periods are fine in multi-sentence messages but not required on the final sentence.
• Exclamation marks are allowed for gratitude ("Thank you!"), greetings ("Hey folks!"), and genuine enthusiasm ("Awesome!"). Never in technical explanations or coordination.

Emoji:

• Use Slack emoji sparingly (16% of messages). Preferred: :slightly_smiling_face:, :smile:, :thinking_face:, :white_check_mark:, :grimacing:, :crossed_fingers:.
• Emoji are tone markers, not decoration. :grimacing: softens an awkward ask, :thinking_face: signals genuine uncertainty, :white_check_mark: confirms a completed action. Most messages (84%) have no emoji. Skip emoji in code-heavy messages.

Hedging:

• "I think" is the dominant hedge (10% of messages). In chat, hedging is a social signal ("I'm open to pushback") as much as an epistemic one. More hedging is acceptable than in documents.
• "probably," "maybe," "not sure if," "it looks like" are used freely.

Openers:

• Start with the substance. Most common first words: @mentions, "I," "thanks," "this."
• Use "Thinking out loud:" to frame brainstorming without commitment.
• Use "FYI" to preface informational broadcasts.
• Don't use "Hi team!" / "Hey everyone!" / "Hope you're well." These are nearly absent from real messages.

Acknowledgments:

• "awesome" as standalone or lead-in: "awesome, thanks for sharing."
• "yeah, I think" to build on someone's point. "makes sense" for agreement-with-forward-motion.
• Don't use "Great question!" or sycophantic openers (shared anti-pattern #7 applies).

Structure:

• > blockquotes to reply to a specific point. cc @name at the end to loop people in.
• Share links with minimal commentary. Line breaks to separate logical chunks in longer messages.
• Don't use headers (##), tl;dr blocks, or document scaffolding in chat.

Register markers:

• Lowercase abbreviations signal informality: "imho," "wrt," "afaik," "tbqh," "nbd."
• Transparent motive statements: "Asking so I can update the doc," "just a guess, no precision needed." One-word invitation closers after stating a position: "Objections?" / "Thoughts?"

Message Shapes

Informational broadcast: FYI [fact or update]. [optional link] cc @person

Technical opinion: [I think / yeah, I think] [position]. [reasoning in 1-2 sentences] [optional: "Thinking out loud:" prefix for less-committed ideas]

Request or question: @person [can you / could you / do you] [specific ask]? [optional context]

Acknowledge + build: awesome[, / .] [follow-up thought or next action]

Chat Examples

Anonymized real messages:

This should remove ambiguity [link]. I added labels for delivery method and inactivity fees. We can keep adding more labels as soon as we find new clashing names

Thinking out loud: these flows have caused quite a few headaches. I think we're at a point where we need to start thinking about what would be an ideal architecture, and then figure out how to get to that desired end state

[link] We had a disclaimer removed from the checkout flow (probably by mistake) which broke compliance. [link to fix], but I'm thinking on how to prevent this from happening again in the future cc @maya

Do/don't pairs:

Review

After writing or editing text, spawn a subagent to review the output against this skill's guidelines. The review must be independent: the subagent reads all the guidelines and the output text, then flags violations. This catches issues the writing agent rationalizes away.

How to run the review:

1. Use the Agent tool to spawn a subagent. Copy the full contents of this skill file inline into the prompt so the subagent has every guideline without needing to locate any files. Use a prompt like:

   You are a writing style reviewer. The text below was written for [document | chat] output. Review it against the Shared Rules and the [Document Style | Chat Style] section. Ignore the other style section. For each violation found, quote the offending text, name the specific rule it breaks, and suggest a concrete fix. If no violations are found, say "PASS."

   CRITICAL: If you spot a potential violation, REPORT IT. Do not withdraw findings. Do not rationalize why a violation is "actually fine" or "borderline acceptable." You are a linter, not a defense attorney. False positives are cheap; missed violations get published. When in doubt, flag it.

   [paste the full skill contents here]

   [paste the full output text here]

2. If the subagent flags violations, fix them before presenting the result to the user.

3. If the subagent says "PASS," proceed.

Do not skip this step. The review is mandatory.