skills/claude-scientific-skills
1
0
Fork 0
mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-27 07:09:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(references): port style guides, 24 diagram guides, and 9 templates from opencode

Browse Source 
All content ported from borealBytes/opencode under Apache-2.0 license with
attribution headers prepended to each file.

- references/markdown_style_guide.md (~733 lines): full markdown formatting,
  citation, collapsible sections, emoji, Mermaid integration, and template
  selection guide
- references/mermaid_style_guide.md (~458 lines): full Mermaid standards —
  emoji set, classDef color palette, accessibility (accTitle/accDescr),
  theme neutrality (no %%{init}), and diagram type selection table
- references/diagrams/ (24 files): per-type exemplars, tips, and templates
  for all Mermaid diagram types
- templates/ (9 files): PR, issue, kanban, ADR, presentation, how-to,
  status report, research paper, project docs

Source: https://github.com/borealBytes/opencode
This commit is contained in:
borealBytes
2026-02-19 18:25:20 -05:00
parent b376b40f59
commit 02e19e3df9
35 changed files with 6687 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

733
scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md Normal file
View File

@@ -0,0 +1,733 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Markdown Style Guide
> **For AI agents:** Read this file for all core formatting rules. When creating any markdown document, follow these conventions for consistent, professional output. When a template exists for your document type, start from it — see [Templates](#templates).
>
> **For humans:** This guide ensures every markdown document in your project is clean, scannable, well-cited, and renders beautifully on GitHub. Reference it from your `AGENTS.md` or contributing guide.
**Target platform:** GitHub Markdown (Issues, PRs, Discussions, Wikis, `.md` files)
**Design goal:** Clear, professional documents that communicate effectively through consistent structure, meaningful formatting, proper citations, and strategic use of diagrams.
---
## Quick Start for Agents
1. **Identify the document type** → Check if a [template](#templates) exists
2. **Structure first** → Heading hierarchy, then content
3. **Apply formatting from this guide** → Headings, text, lists, tables, images, links
4. **Add citations** → Footnote references for all claims and sources
5. **Consider diagrams** → Would a [Mermaid diagram](mermaid_style_guide.md) communicate this better than text?
6. **Add collapsible sections** → For supplementary detail, speaker notes, or lengthy context
7. **Verify** → Run through the [quality checklist](#quality-checklist)
---
## Core Principles
| # | Principle | Rule |
| --- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | **Answer before they ask** | Anticipate reader questions and address them inline. A great document resolves doubts as they form — the reader finishes with no lingering "but what about...?" |
| 2 | **Scannable first** | Readers skim before they read. Use headings, bold, and lists to make the structure visible at a glance. |
| 3 | **Cite everything** | Every claim, statistic, or external reference gets a footnote citation with a full URL. No orphan claims. |
| 4 | **Diagrams over walls of text** | If a concept involves flow, relationships, or structure, use a [Mermaid diagram](mermaid_style_guide.md) alongside the text. |
| 5 | **Generous with information** | Don't hide the details — surface them. Use collapsible sections for depth without clutter, but never omit information because "they probably don't need it." If it's relevant, include it. |
| 6 | **Consistent structure** | Same heading hierarchy, same formatting patterns, same emoji placement across every document. |
| 7 | **One idea per section** | Each heading should cover one topic. If you're covering two ideas, split into two headings. |
| 8 | **Professional but approachable** | Clean formatting, no clutter, no decorative noise — but not stiff or academic. Write like a senior engineer explains to a colleague. |
---
## 🗂️ Everything is Code
Everything is code. PRs, issues, kanban boards — they're all markdown files in your repo, not data trapped in a platform's database.
### Why this matters
- **Portable** — GitHub → GitLab → Gitea → anywhere. Your project management data isn't locked into any vendor. Switch platforms and your issues, PR records, and boards come with you — they're just files.
- **AI-native** — Agents can read every issue, PR record, and kanban board with local file access. No API tokens, no rate limits, no platform-specific queries. `grep` beats `gh api` every time.
- **Auditable** — Project management changes go through the same PR review process as code changes. Every board update, every issue status change — it's all in git history with attribution and timestamps.
### How it works
| What | Where it lives | What GitHub does |
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pull requests** | `docs/project/pr/pr-NNNNNNNN-short-description.md` | GitHub PR is a thin pointer — humans go there to comment on diffs, approve, and watch CI. The record of what changed, why, and what was learned lives in the file. |
| **Issues** | `docs/project/issues/issue-NNNNNNNN-short-description.md` | GitHub Issues is a notification and comment layer. Bug reports, feature requests, investigation logs, and resolutions live in the file. |
| **Kanban boards** | `docs/project/kanban/{scope}-{id}-short-description.md` | No external board tool needed. Modify the board in your branch, merge it with your PR. The board evolves with the codebase. |
| **Decision records** | `docs/decisions/NNN-{slug}.md` | Not tracked in GitHub at all — purely repo-native. |
### The rule
> 📌 **Don't capture information in GitHub's UI that should be captured in a file.** Approve PRs in GitHub. Watch CI in GitHub. Comment in GitHub. But the actual content — the description, the investigation, the decision — lives in a committed file. If it's worth writing down, it's worth committing.
### Templates for tracked documents
- [Pull request record](markdown_templates/pull_request.md) — the PR description IS this file
- [Issue record](markdown_templates/issue.md) — bug reports and feature requests as repo files
- [Kanban board](markdown_templates/kanban.md) — sprint/project boards that merge with your code
See [File conventions](#file-conventions-for-tracked-documents) for directory structure and naming.
---
## Document Structure
### Title and metadata
Every document starts with exactly one H1 title, followed by a brief context line and a separator:
```markdown
# Document Title Here
_Brief context — project name, date, or purpose in one line_
---
```
- **One H1 per document** — never more
- Context line in italics — what this document is, when, and for whom
- Horizontal rule separates metadata from content
### Heading hierarchy
| Level | Syntax | Use | Max per document |
| ----- | --------------- | ----------------------- | ------------------- |
| H1 | `# Title` | Document title | **1** (exactly one) |
| H2 | `## Section` | Major sections | 4–10 |
| H3 | `### Topic` | Topics within a section | 2–5 per H2 |
| H4 | `#### Subtopic` | Subtopics when needed | 2–4 per H3 |
| H5+ | Never use | — | 0 |
**Rules:**
- **Never skip levels** — don't jump from H2 to H4
- **Emoji in H2 headings** — one emoji per H2, at the start: `## 📋 Project Overview`
- **No emoji in H3/H4** — keep sub-headings clean
- **Sentence case** — `## 📋 Project overview` not `## 📋 Project Overview` (exception: proper nouns)
- **Descriptive headings** — `### Authentication flow` not `### Details`
---
## Text Formatting
### Bold, italic, code
| Format | Syntax | When to use | Example |
| ---------- | ------------ | --------------------------------------------- | ----------------------------------- |
| **Bold** | `**text**` | Key terms, important concepts, emphasis | **Primary database** handles writes |
| _Italic_ | `*text*` | Definitions, titles, subtle emphasis | The process is called _sharding_ |
| `Code` | `` `text` `` | Technical terms, commands, file names, values | Run `npm install` to install |
| ~~Strike~~ | `~~text~~` | Deprecated content, corrections | ~~Old approach~~ replaced by v2 |
**Rules:**
- **Bold sparingly** — if everything is bold, nothing is. Max 2–3 bold terms per paragraph.
- **Don't combine** bold and italic (`***text***`) — pick one
- **Code for anything technical** — file names (`README.md`), commands (`git push`), config values (`true`), environment variables (`NODE_ENV`)
- **Never bold entire sentences** — bold the key word(s) within the sentence
### Blockquotes
Use blockquotes for definitions, callouts, and important notes:
```markdown
> **Definition:** A _load balancer_ distributes incoming network traffic
> across multiple servers to ensure no single server bears too much demand.
```
For warnings and callouts:
```markdown
> ⚠️ **Warning:** This operation is destructive and cannot be undone.
> 💡 **Tip:** Use `--dry-run` to preview changes before applying.
> 📌 **Note:** This requires admin permissions on the repository.
```
- Prefix with emoji + bold label for typed callouts
- Keep blockquotes to 1–3 lines
- Don't nest blockquotes (`>>`)
---
## Lists
### When to use each type
| List type | Syntax | Use when |
| --------- | ------------ | ----------------------------------------- |
| Bullet | `- item` | Items have no inherent order |
| Numbered | `1. step` | Steps must happen in sequence |
| Checkbox | `- [ ] item` | Tracking completion (agendas, checklists) |
### Formatting rules
- **Consistent indentation** — 2 spaces for sub-items (some renderers use 4; pick one, stick with it)
- **Parallel structure** — every item in a list should have the same grammatical form
- **No period at end** unless items are full sentences
- **Keep items concise** — if a bullet needs a paragraph, it should be a sub-section instead
- **Max nesting depth: 2 levels** — if you need a third level, restructure
```markdown
✅ Good — parallel structure, concise:
- Configure the database connection
- Run the migration scripts
- Verify the schema changes
❌ Bad — mixed structure, verbose:
- You need to configure the database
- Migration scripts
- After that, you should verify that the schema looks correct
```
---
## Links and Citations
### Inline links
```markdown
See the [Mermaid Style Guide](mermaid_style_guide.md) for diagram conventions.
```
- **Meaningful link text** — `[Mermaid Style Guide]` not `[click here]` or `[link]`
- **Relative paths** for internal links — `[Guide](./README.md)` not absolute URLs
- **Full URLs** for external links — always `https://`
### Footnote citations
**Every claim, statistic, or reference to external work MUST have a footnote citation.** This is non-negotiable for credibility.
```markdown
Markdown was created by John Gruber in 2004 as a lightweight
markup language designed for readability[^1]. GitHub adopted
Mermaid diagram support in February 2022[^2].
[^1]: Gruber, J. (2004). "Markdown." _Daring Fireball_. https://daringfireball.net/projects/markdown/
[^2]: GitHub Blog. (2022). "Include diagrams in your Markdown files with Mermaid." https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
```
**Citation format:**
```
[^N]: Author/Org. (Year). "Title." *Publication*. https://full-url
```
**Rules:**
- **Number sequentially** — `[^1]`, `[^2]`, `[^3]` in order of appearance
- **Full URL always included** — the reader must be able to reach the source
- **Group all footnotes at the document bottom** — under a `## References` section or at the very end
- **Every external claim needs one** — statistics, quotes, methodologies, tools mentioned
- **Internal project links don't need footnotes** — use inline links instead
### Reference-style links (for repeated URLs)
When the same URL appears multiple times, use reference-style links to keep the text clean:
```markdown
The [official docs][mermaid-docs] cover all diagram types.
See [Mermaid documentation][mermaid-docs] for the full syntax.
[mermaid-docs]: https://mermaid.js.org/ 'Mermaid Documentation'
```
---
## Images and Figures
### Placement and syntax
```markdown
![Descriptive alt text for screen readers](images/architecture_overview.png)
_Figure 1: System architecture showing the three-tier deployment model_
```
**Rules:**
- **Inline with content** — place images where they're relevant, not in a separate "Images" section
- **Descriptive alt text** — `![Three-tier architecture diagram]` not `![image]` or `![screenshot]`
- **Italic caption below** — `*Figure N: What this image shows*`
- **Number figures sequentially** — Figure 1, Figure 2, etc. if multiple images
- **Relative paths** — `images/file.png` not absolute paths
- **Reasonable file sizes** — compress PNGs, use SVG where possible
### Image naming convention
```
{document-slug}_{description}.{ext}
Examples:
auth_flow_overview.png
deployment_architecture.svg
api_response_example.png
```
### When NOT to use an image
If the content could be expressed as a **Mermaid diagram**, prefer that over a static image:
| Scenario | Use |
| -------------------------- | ------------------------------------------ |
| Architecture diagram | Mermaid `flowchart` or `architecture-beta` |
| Sequence/interaction | Mermaid `sequenceDiagram` |
| Data model | Mermaid `erDiagram` |
| Timeline | Mermaid `timeline` or `gantt` |
| Screenshot of UI | Image (Mermaid can't do this) |
| Photo / real-world image | Image |
| Complex data visualization | Image or Mermaid `xychart-beta` |
See the [Mermaid Style Guide](mermaid_style_guide.md) for diagram type selection and styling.
---
## Tables
### When to use tables
- **Structured comparisons** — features, options, tradeoffs
- **Reference data** — configuration values, API parameters, status codes
- **Schedules and matrices** — timelines, responsibility assignments
### When NOT to use tables
- **Narrative content** — use paragraphs instead
- **Simple lists** — use bullet points
- **More than 5 columns** — becomes unreadable on mobile; restructure
### Formatting
```markdown
| Feature | Free Tier | Pro Tier | Enterprise |
| ------- | --------- | -------- | ---------- |
| Users | 5 | 50 | Unlimited |
| Storage | 1 GB | 100 GB | Custom |
| Support | Community | Email | Dedicated |
```
**Rules:**
- **Header row always** — no headerless tables
- **Left-align text columns** — `|---|` (default)
- **Right-align number columns** — `|---:|` when appropriate
- **Concise cell content** — 1–5 words per cell. If you need more, it's not a table problem
- **Bold key column** — the first column or the column the reader scans first
- **Consistent formatting within columns** — don't mix sentences and fragments
---
## Code Blocks
### Inline code
Use backticks for technical terms within prose:
```markdown
Run `git status` to check for uncommitted changes.
The `NODE_ENV` variable controls the runtime environment.
```
### Fenced code blocks
Always specify the language for syntax highlighting:
````markdown
```python
def calculate_average(values: list[float]) -> float:
"""Return the arithmetic mean of a list of values."""
return sum(values) / len(values)
```
````
**Rules:**
- **Always include language identifier** — ` ```python `, ` ```bash `, ` ```json `, etc.
- **Use ` ```text ` for plain output** — not ` ``` ` with no language
- **Keep blocks focused** — show the relevant snippet, not the entire file
- **Add a comment if context needed** — `# Configure the database connection` at the top of the block
---
## Collapsible Sections
Use HTML `<details>` for supplementary content that shouldn't clutter the main flow — speaker notes, implementation details, verbose logs, or optional deep-dives.
```markdown
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- Key talking point one
- Transition to next topic
- **Bold** emphasis works inside details
- [Links](https://example.com) work too
</details>
---
```
**Rules:**
- **Collapsed by default** — the `<details>` tag collapses automatically
- **Descriptive summary** — `<strong>💬 Speaker Notes</strong>` or `<strong>📋 Implementation Details</strong>`
- **Blank line after `<summary>` tag** — required for markdown to render inside the block
- **ALWAYS follow with `---`** — horizontal rule after every `</details>` for visual separation
- **Any markdown works inside** — bullets, bold, links, code blocks, tables
### Common collapsible patterns
| Summary label | Use for |
| --------------------- | ------------------------------------------------ |
| 💬 **Speaker Notes** | Presentation talking points, timing, transitions |
| 📋 **Details** | Extended explanation, verbose context |
| 🔧 **Implementation** | Technical details, code samples, config |
| 📊 **Raw Data** | Full output, logs, data tables |
| 💡 **Background** | Context that helps but isn't essential |
---
## Horizontal Rules
Use `---` (three hyphens) for visual separation:
```markdown
---
```
**When to use:**
- **After every `</details>` block** — mandatory, creates clear separation
- **After title/metadata** — separates document header from content
- **Between major sections** — when an H2 heading alone doesn't create enough visual break
- **Before footnotes/references** — separates content from citation list
**When NOT to use:**
- Between every paragraph (too busy)
- Between H3 sub-sections within the same H2 (use whitespace instead)
---
## Approved Emoji Set
One emoji per H2 heading, at the start. Use sparingly in body text for callouts and emphasis only.
### Section headings
| Emoji | Use for |
| ----- | -------------------------------------- |
| 📋 | Overview, summary, agenda, checklist |
| 🎯 | Goals, objectives, outcomes, targets |
| 📚 | Content, documentation, main body |
| 🔗 | Resources, references, links |
| 📍 | Agenda, navigation, current position |
| 🏠 | Housekeeping, logistics, announcements |
| ✍️ | Tasks, assignments, action items |
### Status and outcomes
| Emoji | Meaning |
| ----- | ------------------------------------ |
| ✅ | Success, complete, correct, approved |
| ❌ | Failure, incorrect, avoid, rejected |
| ⚠️ | Warning, caution, important notice |
| 💡 | Tip, insight, idea, best practice |
| 📌 | Important, key point, remember |
| 🚫 | Prohibited, do not, blocked |
### Technical and process
| Emoji | Meaning |
| ----- | --------------------------------- |
| ⚙️ | Configuration, settings, process |
| 🔧 | Tools, utilities, setup |
| 🔍 | Analysis, investigation, review |
| 📊 | Data, metrics, analytics |
| 📈 | Growth, trends, improvement |
| 🔄 | Cycle, refresh, iteration |
| ⚡ | Performance, speed, quick action |
| 🔐 | Security, authentication, privacy |
| 🌐 | Web, API, network, global |
| 💾 | Storage, database, persistence |
| 📦 | Package, artifact, deployment |
### People and collaboration
| Emoji | Meaning |
| ----- | ----------------------------------- |
| 👤 | User, person, individual |
| 👥 | Team, group, collaboration |
| 💬 | Discussion, comments, speaker notes |
| 🎓 | Learning, education, knowledge |
| 🤔 | Question, consideration, reflection |
### Emoji rules
1. **One per H2 heading** at the start — `## 📋 Overview`
2. **None in H3/H4** — keep sub-headings clean
3. **Sparingly in body text** — for callouts (`> ⚠️ **Warning:**`) and key markers only
4. **Never in**: titles (H1), code blocks, link text, table data cells
5. **No decorative emoji** — 🎉 💯 🔥 🎊 💥 ✨ add noise, not meaning
6. **Consistency** — same emoji = same meaning across all documents in the project
---
## Mermaid Diagram Integration
**Whenever content describes flow, structure, relationships, or processes, consider whether a Mermaid diagram would communicate it better than prose alone.** Diagrams and text together are more effective than either alone.
### When to add a diagram
**Any time your text describes flow, structure, relationships, timing, or comparisons, there's a Mermaid diagram that communicates it better.** Scan the table below to identify the right type, then follow this workflow:
1. **Read the [Mermaid Style Guide](mermaid_style_guide.md) first** — emoji, color palette, accessibility, complexity management
2. **Then open the specific type file** — exemplar, tips, template, complex example
| Your content describes... | Add a... | Type file |
| ---------------------------------------------------- | ------------------------ | --------------------------------------------------- |
| Steps in a process, workflow, decision logic | **Flowchart** | [flowchart.md](mermaid_diagrams/flowchart.md) |
| Who talks to whom and when (API calls, messages) | **Sequence diagram** | [sequence.md](mermaid_diagrams/sequence.md) |
| Class hierarchy, type relationships, interfaces | **Class diagram** | [class.md](mermaid_diagrams/class.md) |
| Status transitions, entity lifecycle, state machine | **State diagram** | [state.md](mermaid_diagrams/state.md) |
| Database schema, data model, entity relationships | **ER diagram** | [er.md](mermaid_diagrams/er.md) |
| Project timeline, roadmap, task dependencies | **Gantt chart** | [gantt.md](mermaid_diagrams/gantt.md) |
| Parts of a whole, proportions, distribution | **Pie chart** | [pie.md](mermaid_diagrams/pie.md) |
| Git branching strategy, merge/release flow | **Git Graph** | [git_graph.md](mermaid_diagrams/git_graph.md) |
| Concept hierarchy, brainstorm, topic map | **Mindmap** | [mindmap.md](mermaid_diagrams/mindmap.md) |
| Chronological events, milestones, history | **Timeline** | [timeline.md](mermaid_diagrams/timeline.md) |
| User experience, satisfaction scores, journey | **User Journey** | [user_journey.md](mermaid_diagrams/user_journey.md) |
| Two-axis comparison, prioritization matrix | **Quadrant chart** | [quadrant.md](mermaid_diagrams/quadrant.md) |
| Requirements traceability, compliance mapping | **Requirement diagram** | [requirement.md](mermaid_diagrams/requirement.md) |
| System architecture at varying zoom levels | **C4 diagram** | [c4.md](mermaid_diagrams/c4.md) |
| Flow magnitude, resource distribution, budgets | **Sankey diagram** | [sankey.md](mermaid_diagrams/sankey.md) |
| Numeric trends, bar charts, line charts | **XY Chart** | [xy_chart.md](mermaid_diagrams/xy_chart.md) |
| Component layout, spatial arrangement, layers | **Block diagram** | [block.md](mermaid_diagrams/block.md) |
| Work item tracking, status board, task columns | **Kanban board** | [kanban.md](mermaid_diagrams/kanban.md) |
| Binary protocol layout, data packet format | **Packet diagram** | [packet.md](mermaid_diagrams/packet.md) |
| Cloud infrastructure, service topology, networking | **Architecture diagram** | [architecture.md](mermaid_diagrams/architecture.md) |
| Multi-dimensional comparison, skills, radar analysis | **Radar chart** | [radar.md](mermaid_diagrams/radar.md) |
| Hierarchical proportions, budget breakdown | **Treemap** | [treemap.md](mermaid_diagrams/treemap.md) |
> 💡 **Pick the right type, not the easy type.** Don't default to flowcharts for everything — a timeline is better than a flowchart for chronological events, a sequence diagram is better for service interactions, an ER diagram is better for data models. Scan the table above and match your content to the most specific type. **If you catch yourself writing a paragraph that describes a visual concept, stop and diagram it.**
### How to integrate
Place the diagram **inline with the related text**, not in a separate section:
````markdown
### Authentication Flow
The login process validates credentials, checks MFA status,
and issues session tokens. Failed attempts are logged for
security monitoring.
‎```mermaid
sequenceDiagram
accTitle: Login Authentication Flow
accDescr: User login sequence through API and auth service
participant U as 👤 User
participant A as 🌐 API
participant S as 🔐 Auth Service
U->>A: POST /login
A->>S: Validate credentials
S-->>A: ✅ Token issued
A-->>U: 200 OK + session
‎```
The token expires after 24 hours. See [Authentication flow](#authentication-flow)
for refresh token details.
````
**Always follow the [Mermaid Style Guide](mermaid_style_guide.md)** for diagram styling — emoji, color classes, accessibility (`accTitle`/`accDescr`), and type-specific conventions.
---
## Whitespace and Spacing
- **Blank line between paragraphs** — always
- **Blank line before and after headings** — always
- **Blank line before and after code blocks** — always
- **Blank line before and after blockquotes** — always
- **No blank line between list items** — keep lists tight
- **No trailing whitespace** — clean line endings
- **One blank line at end of file** — standard convention
- **No more than one consecutive blank line** — two blank lines = too much space
---
## Quality Checklist
### Structure
- [ ] Exactly one H1 title
- [ ] Heading hierarchy is correct (H1 → H2 → H3 → H4, no skips)
- [ ] Each H2 has exactly one emoji at the start
- [ ] H3 and H4 have no emoji
- [ ] Horizontal rules after title metadata and after every `</details>` block
### Content
- [ ] Every external claim has a footnote citation
- [ ] All footnotes have full URLs
- [ ] All links tested and working
- [ ] Meaningful link text (no "click here")
- [ ] Bold used for key terms, not entire sentences
- [ ] Code formatting for all technical terms
### Visual elements
- [ ] Images have descriptive alt text
- [ ] Images have italic figure captions
- [ ] Images placed inline with related content (not in separate section)
- [ ] Tables have header rows and consistent formatting
- [ ] Mermaid diagrams considered where applicable (with `accTitle`/`accDescr`)
### Collapsible sections
- [ ] `<details>` blocks have descriptive `<summary>` labels
- [ ] Blank line after `<summary>` tag (for markdown rendering)
- [ ] Horizontal rule `---` after every `</details>` block
- [ ] Content inside collapses renders correctly
### Polish
- [ ] No spelling or grammar errors
- [ ] Consistent whitespace (no trailing spaces, no double blanks)
- [ ] Parallel grammatical structure in lists
- [ ] Renders correctly in GitHub light and dark mode
---
## Templates
Templates provide pre-built structures for common document types. Copy the template, fill in your content, and follow this style guide for formatting. Every template enforces the principles above — citations, diagrams, collapsible depth, and self-answering structure.
| Document type | Template | Best for |
| ------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Presentation / briefing | [presentation.md](markdown_templates/presentation.md) | Slide-deck-style documents with speaker notes, structured sections, and visual flow |
| Research paper / analysis | [research_paper.md](markdown_templates/research_paper.md) | Data-driven analysis, literature reviews, methodology + findings with heavy citations |
| Project documentation | [project_documentation.md](markdown_templates/project_documentation.md) | Software/product docs — architecture, getting started, API reference, contribution guide |
| Decision record (ADR/RFC) | [decision_record.md](markdown_templates/decision_record.md) | Recording why a decision was made — context, options evaluated, outcome, consequences |
| How-to / tutorial guide | [how_to_guide.md](markdown_templates/how_to_guide.md) | Step-by-step instructions with prerequisites, verification steps, and troubleshooting |
| Status report / executive brief | [status_report.md](markdown_templates/status_report.md) | Progress updates, risk summaries, decisions needed — for leadership and stakeholders |
| Pull request record | [pull_request.md](markdown_templates/pull_request.md) | PR documentation with change inventory, testing evidence, rollback plan, and review notes |
| Issue record | [issue.md](markdown_templates/issue.md) | Bug reports (reproduction steps, root cause) and feature requests (acceptance criteria, user stories) |
| Kanban board | [kanban.md](markdown_templates/kanban.md) | Sprint/release/project work tracking with visual board, WIP limits, metrics, and blocked items |
### File conventions for tracked documents
Some templates produce documents that accumulate over time. Use these directory conventions:
| Document type | Directory | Naming pattern | Example |
| ---------------- | ---------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| Pull requests | `docs/project/pr/` | `pr-NNNNNNNN-short-description.md` | `docs/project/pr/pr-00000123-fix-auth-timeout.md` |
| Issues | `docs/project/issues/` | `issue-NNNNNNNN-short-description.md` | `docs/project/issues/issue-00000456-add-export-filter.md` |
| Kanban boards | `docs/project/kanban/` | `{scope}-{identifier}-short-description.md` | `docs/project/kanban/sprint-2026-w07-agentic-template-modernization.md` |
| Decision records | `docs/decisions/` | `NNN-{slug}.md` | `docs/decisions/001-use-postgresql.md` |
| Status reports | `docs/status/` | `status-{date}.md` | `docs/status/status-2026-02-14.md` |
### Choosing a template
- **Presenting to people?** → Presentation
- **Publishing analysis or research?** → Research paper
- **Documenting a codebase or product?** → Project documentation
- **Recording why you chose X over Y?** → Decision record
- **Teaching someone how to do something?** → How-to guide
- **Updating leadership on progress?** → Status report
- **Documenting a PR for posterity?** → Pull request record
- **Tracking a bug or requesting a feature?** → Issue record
- **Managing work items for a sprint or project?** → Kanban board
- **None of these fit?** → Start from this style guide's rules directly — no template required
---
## Common Mistakes
### ❌ Multiple emoji per heading
```markdown
## 📚📊📈 Content Topics ← Too many
```
✅ Fix: One emoji per H2
```markdown
## 📚 Content topics
```
### ❌ Missing citations
```markdown
Studies show 73% of developers prefer Markdown. ← Where's the source?
```
✅ Fix: Add footnote
```markdown
Studies show 73% of developers prefer Markdown[^1].
[^1]: Stack Overflow. (2024). "Developer Survey Results." https://survey.stackoverflow.co/2024
```
### ❌ Wall of text without structure
```markdown
The system handles authentication by first checking the JWT token
validity, then verifying the user exists in the database, then
checking their permissions against the requested resource...
```
✅ Fix: Use a list, heading, or diagram
```markdown
### Authentication flow
1. Validate JWT token signature and expiration
2. Verify user exists in the database
3. Check user permissions against the requested resource
```
### ❌ Images in a separate section
```markdown
## Content
[paragraphs of text]
## Screenshots
[all images grouped here] ← Disconnected from context
```
✅ Fix: Place images inline where relevant
### ❌ No horizontal rule after collapsible sections
```markdown
</details>
### Next Topic ← Runs together visually
```
✅ Fix: Always add `---` after `</details>`
```markdown
</details>
---
### Next topic ← Clear separation
```
---
## Resources
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/) · [Mermaid Style Guide](mermaid_style_guide.md) · [GitHub Basic Formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)