Technical Writer

The document generator. Given knowledge, context, and a document type, this skill produces polished markdown. It does not collect requirements or manage workflows — it writes.

Other skills feed into this one. For example, write-tickets gathers JIRA inputs, research, and ticket plans, then passes the collected data here to generate the markdown. Any skill or user can invoke this the same way: provide the type, the knowledge, and get back a well-structured document.

Core Writing Principles

These apply to ALL document types:

1. Research before writing. Explore the codebase and/or search online BEFORE drafting. A "big project" is often a "5-line config change."
2. No assumptions. Only include verified findings. No "likely" or "probably."
3. Point to the door, don't walk them through the house. Give entry points and constraints, not exhaustive file lists or step-by-step instructions.
4. Concise over comprehensive. Every sentence should earn its place. Cut filler.
5. Markdown always. All output in Markdown.
6. GitHub links for code. Never local paths. Always [file.ts#L45](https://github.com/org/repo/blob/main/path/file.ts#L45).
7. No open questions in output. Ask the user BEFORE writing. The document should be actionable.
8. Preserve source links. If the user provides URLs (docs, Slack, Confluence), include them automatically. Don't add vague references without actual URLs.
9. Include code examples when needed. Use short code blocks or snippets when they clarify: bug reproduction steps, config/schema examples, API usage, or "before/after" in ADRs or docs. In ticket Tech Specs prefer links and bullets; in documentation, spikes, reports, and ADRs use code freely when it helps the reader.

How This Skill Is Used

Called by another skill (e.g. write-tickets)

The calling skill provides:

1. Document type (ticket-story, ticket-bug, spike, report, adr, etc.)
2. Collected knowledge (requirements, research findings, context, links)

This skill then:

1. Reads the appropriate template
2. Generates the markdown
3. Returns it to the calling skill

Called directly by the user

When a user asks to write/draft a document directly:

Step 1: Determine document type. Use AskQuestion if not clear from context:

AskQuestion({
  "title": "Document Type",
  "questions": [
    {
      "id": "type",
      "prompt": "What type of document should I write?",
      "options": [
        {"id": "ticket-story", "label": "Ticket - Story / Feature"},
        {"id": "ticket-bug", "label": "Ticket - Bug Report"},
        {"id": "ticket-tech-debt", "label": "Ticket - Tech Debt"},
        {"id": "ticket-spike", "label": "Ticket - Spike / Investigation"},
        {"id": "pr-description", "label": "PR Description"},
        {"id": "plan", "label": "Plan (Development / Migration / Project / Rollout)"},
        {"id": "docs", "label": "Documentation (Feature)"},
        {"id": "spike", "label": "Spike / Investigation"},
        {"id": "report", "label": "Technical Report / Summary"},
        {"id": "adr", "label": "Architecture Decision Record"},
        {"id": "rfc", "label": "RFC / Proposal"},
        {"id": "other", "label": "Something else"}
      ]
    }
  ]
})

Step 2: Collect inputs. Ask: "Provide your requirements, context, or raw input (meeting notes, Slack threads, rough ideas, etc.)"

Step 3: Generate. Read the template, draft the document, present to user.

Step 4: Confirm. Use AskQuestion:

AskQuestion({
  "title": "Review Draft",
  "questions": [{
    "id": "review",
    "prompt": "How does this look?",
    "options": [
      {"id": "approve", "label": "Looks good"},
      {"id": "feedback", "label": "I have feedback"},
      {"id": "redo", "label": "Start over"}
    ]
  }]
})

Refine until approved.

Step 5: Deliver. Use AskQuestion:

AskQuestion({
  "title": "Output",
  "questions": [{
    "id": "output",
    "prompt": "How would you like the output?",
    "options": [
      {"id": "clipboard", "label": "Copy to clipboard"},
      {"id": "file", "label": "Save to file"},
      {"id": "done", "label": "Already have it, thanks"}
    ]
  }]
})

Templates

Read the appropriate template when writing each document type. All templates are in this skill's templates/ directory.

Ticket Templates (ticket-*)

Used when writing JIRA tickets or standalone ticket descriptions.

PR Description

Used when writing pull request descriptions (jira/what/why/who format). Can be called by dev-workflow-create-pr (which supplies diff + ticket and may wrap output in [[[ / ]]]) or directly.

PR description rules:

• Output only the jira / what / why / who block; no extra headers or preamble.
• Keep each field concise (1–2 sentences; use bullets for "what" only when there are multiple distinct changes).
• Use backticks for code references. Link format: RETIRE branches → gustohq.atlassian.net; others → internal.guideline.tools/jira.
• Do not add indentation inside the block.

Plan Templates (plan-*)

Used when summarizing brainstorming sessions, strategy discussions, or project scoping into a structured plan.

Documentation Templates (docs-*)

Used when documenting existing or newly shipped features.

Document Templates

Used when writing standalone documents, reports, or decision records.

Template Routing

Match the ask to the template:

Ticket Writing Rules

These apply when writing any ticket (feature, bug, tech debt, spike):

Scoping tickets:

• UI work is often a separate ticket (different skillset, different reviewer)
• Risky migrations (column deletes, renames, type changes) always get their own ticket
• Model + API changes for the same feature stay as ONE ticket
• Simple migrations bundled with the feature they enable stay together
• Changes that must be deployed together stay together

Ordering:

• Dependencies/prerequisites come first in the list
• Present tickets in dependency order so each can reference the ones before it

Tech Specs (all ticket types):

• 3-5 bullet points max
• Entry points only - where to start looking, not every file that might change
• Name patterns to reuse: "follow the X pattern" with one link
• Constraints and gotchas that will bite the implementer
• No "Files to Create" or "Files to Modify" sections
• Prefer links and bullets over code blocks here; use a short code example only when it's the clearest way to show a gotcha (e.g. a required wrapper or config line)

Example Tech Specs section:

## Tech Specs

- Entry point: [useUserAccounts.ts](https://github.com/guideline-app/mobile-app/blob/main/src/features/me/hooks/useUserAccounts.ts)
- Follow pattern from [usePortfolio.ts](https://github.com/guideline-app/mobile-app/blob/main/src/features/portfolio/hooks/usePortfolio.ts)
- Gotcha: Suspense queries require a Suspense boundary - wrap in `<Suspense fallback={<LoadingScreen />}>`

What NOT to include in tickets:

• "Dependencies", "Scope Boundaries", "In Scope", "Open Questions", "Data Model", "Implementation Steps", "Files to Create", "Success Metrics" sections
• Exhaustive lists of related files
• Step-by-step implementation instructions
• Long code examples or class structures in Tech Specs (short snippets for gotchas are fine when they clarify)

Multiple tickets from one input:

• Analyze input for natural ticket boundaries
• Confirm the ticket plan (list + order) before writing any tickets
• Write and confirm each ticket sequentially so JIRA keys are available for cross-references

Writing Style Guide

Tone: Direct, professional, no fluff. Write like a senior engineer documenting for other senior engineers.

Structure:

• Lead with the conclusion/decision/recommendation
• Context comes second (reader already knows why they opened this doc)
• Use bullet points over paragraphs where possible
• Tables for comparisons, always

Technical references:

• 3-5 bullet points max for tech specs
• Entry points only, not every file
• Name patterns to reuse with one link
• Constraints and gotchas that will bite someone

Code examples:

• Include code when it helps: bug reproduction, config snippets, API usage, before/after in ADRs, or feature docs. Keep examples short and focused.
• In ticket Tech Specs prefer links; use a code snippet only when it's the clearest way to convey a constraint or gotcha.

What to cut:

• Background the reader already knows
• Obvious statements ("we need to test this")
• Hedging language ("it might be good to consider")
• Redundant sections across templates

Common Mistakes