skills/claude-scientific-skills
1
0
Fork 0
mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-29 07:43:46 +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:
Clayton Young
2026-02-19 18:25:20 -05:00
parent 21f8536cef
commit 39bb842a21
35 changed files with 6687 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
scientific-skills/markdown-mermaid-writing/templates/decision_record.md Normal file
View File

@@ -0,0 +1,211 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Decision Record (ADR/RFC) Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Architecture Decision Records (ADRs), Requests for Comment (RFCs), technical design documents, or any decision that needs to be documented with its context, options considered, and rationale. Designed so that future teams understand not just _what_ was decided, but _why_ — and can evaluate whether the decision still holds.
**Key features:** Structured options comparison with explicit tradeoffs, decision matrix, consequences section that captures both benefits and risks, and status tracking for the decision lifecycle.
**Philosophy:** Decisions rot faster than code. Six months from now, someone will ask "why did we do it this way?" If the answer is "nobody remembers," the decision is as good as random. This template makes the reasoning permanent, searchable, and evaluable. It also forces the author to genuinely consider alternatives — if you can't articulate why you rejected Option B, you haven't done enough analysis.
---
## How to Use
1. Copy this file to your project's `docs/decisions/` or `adr/` directory
2. Name it sequentially: `001-use-postgresql-over-mongodb.md`
3. Replace all `[bracketed placeholders]` with your content
4. **Present options honestly** — don't set up straw men just to knock them down
5. Add [Mermaid diagrams](../mermaid_style_guide.md) for architecture comparisons, data flow changes, or migration paths
---
## The Template
Everything below the line is the template. Copy from here:
---
# [ADR-NNN]: [Decision Title — Clear and Specific]
| Field | Value |
| ------------------- | ---------------------------------------------------------- |
| **Status** | [Proposed / Accepted / Deprecated / Superseded by ADR-NNN] |
| **Date** | [YYYY-MM-DD] |
| **Decision makers** | [Names or roles] |
| **Consulted** | [Who was asked for input] |
| **Informed** | [Who needs to know the outcome] |
---
## 📋 Context
### What prompted this decision?
[Describe the situation that requires a decision. What changed? What problem emerged? What opportunity appeared? Be specific — include metrics, incidents, or user feedback that triggered this.]
### Current state
[How things work today. What architecture, tool, or process is currently in place. Include a diagram if it helps.]
```mermaid
flowchart LR
accTitle: Current State Architecture
accDescr: How the system works today before this decision is implemented
a[⚙️ Current component] --> b[💾 Current dependency]
b --> c[📤 Current output]
```
### Constraints
- **[Constraint 1]:** [Budget, timeline, team size, compliance requirement, etc.]
- **[Constraint 2]:** [Technical constraint, backward compatibility, SLA, etc.]
- **[Constraint 3]:** [Organizational constraint, vendor lock-in, skills gap, etc.]
### Requirements
This decision must:
- [ ] [Requirement 1 — specific and measurable]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
---
## 🔍 Options Considered
### Option A: [Name]
**Description:** [What this option entails — 2–3 sentences]
**Pros:**
- [Specific benefit with evidence if available]
- [Another benefit]
**Cons:**
- [Specific drawback with impact assessment]
- [Another drawback]
**Estimated effort:** [T-shirt size or days/weeks]
**Estimated cost:** [If relevant — licensing, infrastructure, personnel]
### Option B: [Name]
**Description:** [What this option entails]
**Pros:**
- [Benefit]
- [Benefit]
**Cons:**
- [Drawback]
- [Drawback]
**Estimated effort:** [Estimate]
**Estimated cost:** [If relevant]
### Option C: [Name] _(if applicable)_
**Description:** [What this option entails]
**Pros:**
- [Benefit]
**Cons:**
- [Drawback]
**Estimated effort:** [Estimate]
### Decision matrix
| Criterion | Weight | Option A | Option B | Option C |
| --------------------------------------- | -------------- | ------------------- | -------- | -------- |
| [Criterion 1 — e.g., Performance] | [High/Med/Low] | [Score or ✅/⚠️/❌] | [Score] | [Score] |
| [Criterion 2 — e.g., Team expertise] | [Weight] | [Score] | [Score] | [Score] |
| [Criterion 3 — e.g., Migration effort] | [Weight] | [Score] | [Score] | [Score] |
| [Criterion 4 — e.g., Long-term cost] | [Weight] | [Score] | [Score] | [Score] |
| [Criterion 5 — e.g., Community/support] | [Weight] | [Score] | [Score] | [Score] |
---
## 🎯 Decision
**We chose Option [X]: [Name].**
[2–3 sentences explaining the core rationale. What tipped the decision? Which criteria mattered most and why?]
### Why not the others?
- **Option [Y] was rejected because:** [Specific reason — not "it wasn't good enough" but "the migration effort would take 3 sprints and delay the Q2 launch"]
- **Option [Z] was rejected because:** [Specific reason]
---
## ⚡ Consequences
### Positive
- [Benefit 1 — what improves, with expected impact]
- [Benefit 2]
### Negative
- [Tradeoff 1 — what we lose or what becomes harder]
- [Tradeoff 2]
### Risks
| Risk | Likelihood | Impact | Mitigation |
| -------- | -------------- | -------------- | --------------------- |
| [Risk 1] | [Low/Med/High] | [Low/Med/High] | [How we'll handle it] |
| [Risk 2] | [Likelihood] | [Impact] | [Mitigation] |
### Implementation impact
```mermaid
flowchart LR
accTitle: Post-Decision Architecture
accDescr: How the system will work after this decision is implemented
a[⚙️ New component] --> b[💾 New dependency]
b --> c[📤 New output]
```
---
## 📋 Implementation plan
| Step | Owner | Target date | Status |
| -------- | ------------- | ----------- | ---------------------------------- |
| [Step 1] | [Person/Team] | [Date] | [Not started / In progress / Done] |
| [Step 2] | [Person/Team] | [Date] | [Status] |
| [Step 3] | [Person/Team] | [Date] | [Status] |
---
## 🔗 References
- [Related ADR or RFC](../adr/ADR-001-agent-optimized-documentation-system.md)
- [External documentation or benchmark](https://example.com)
- [Relevant issue or discussion thread](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
---
## Review log
| Date | Reviewer | Outcome |
| ------ | -------- | ----------------------------------------- |
| [Date] | [Name] | [Proposed / Approved / Requested changes] |
---
_Last updated: [Date]_

275
scientific-skills/markdown-mermaid-writing/templates/how_to_guide.md Normal file
View File

@@ -0,0 +1,275 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# How-To / Tutorial Guide Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Step-by-step tutorials, how-to guides, onboarding walkthroughs, runbooks, setup instructions, or any document whose primary job is teaching someone to do something. Designed so the reader succeeds on the first attempt.
**Key features:** Prerequisites with verification commands, numbered steps with expected output at each stage, "verify it works" checkpoints, troubleshooting section for common failures, and "what's next" pathways.
**Philosophy:** A how-to guide fails if the reader gets stuck. Every step should be verifiable — the reader should be able to confirm they did it right before moving to the next one. Anticipate the exact moment they'll wonder "did that work?" and put a checkpoint there. Include the error messages they'll actually see, not just the happy path.
---
## How to Use
1. Copy this file to your project
2. Replace all `[bracketed placeholders]` with your content
3. **Test the guide yourself from scratch** — follow every step on a clean machine. If you skip this, the guide has bugs.
4. Add [Mermaid diagrams](../mermaid_style_guide.md) for process overviews, decision points, or architecture context
5. Include actual output (trimmed) at every verification step — don't just say "you should see output"
---
## The Template
Everything below the line is the template. Copy from here:
---
# [How to: Specific Task Description]
_[Estimated time: N minutes] · [Difficulty: Beginner / Intermediate / Advanced] · [Last verified: Date]_
---
## 📋 Overview
### What you'll accomplish
[One paragraph: what the reader will have built, configured, or achieved by the end of this guide. Be concrete.]
### What you'll learn
- [Skill or concept 1]
- [Skill or concept 2]
- [Skill or concept 3]
### Process overview
```mermaid
flowchart LR
accTitle: Tutorial Process Overview
accDescr: High-level steps from prerequisites through setup, configuration, and verification
prereqs([📋 Prerequisites]) --> setup[🔧 Setup]
setup --> configure[⚙️ Configure]
configure --> build[📦 Build]
build --> verify[✅ Verify]
classDef done fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class verify done
```
---
## 📋 Prerequisites
Before starting, ensure you have:
| Requirement | Version | Verify with | Install link |
| ---------------- | ----------- | --------------------- | ------------------------------------ |
| [Tool/Runtime] | ≥ [version] | `[command] --version` | [Install guide](https://example.com) |
| [Dependency] | ≥ [version] | `[command] --version` | [Install guide](https://example.com) |
| [Account/Access] | — | [How to verify] | [Sign up](https://example.com) |
**Verify all prerequisites:**
```bash
# Run each command — all should succeed before proceeding
[command1] --version # Expected: [version] or higher
[command2] --version # Expected: [version] or higher
```
> ⚠️ **Don't skip this.** Step 3 will fail if [specific prerequisite] isn't installed correctly.
---
## 🔧 Steps
### Step 1: [Action verb — Set up / Create / Configure / Install]
[Brief context: why this step is necessary — one sentence.]
```bash
[command to run]
```
**Expected output:**
```
[What the terminal should show — include actual output, trimmed if long]
```
> 💡 **Tip:** [Helpful context about this step — common variation, what to do if on a different OS, etc.]
---
### Step 2: [Action verb]
[Brief context.]
```bash
[command to run]
```
**Expected output:**
```
[What you should see]
```
**If you see an error here**, check:
- [Most common cause and fix]
- [Second most common cause and fix]
---
### Step 3: [Action verb]
[Brief context.]
[If this step involves editing a file, show the exact content:]
```yaml
# config/[filename]
[key]: [value]
[key]: [value]
# [Comment explaining what this section does]
[key]:
[nested_key]: [value]
[nested_key]: [value]
```
> 📌 **Important:** [Critical detail about this configuration — what breaks if you get it wrong]
---
### Step 4: [Action verb]
[Brief context.]
```bash
[command to run]
```
**Expected output:**
```
[What you should see]
```
---
### Step 5: [Action verb — this should be the final action]
[Brief context.]
```bash
[final command]
```
---
## ✅ Verify it works
Run through these checks to confirm everything is working:
| Check | Command | Expected result |
| --------- | ----------- | ------------------------- |
| [Check 1] | `[command]` | [What success looks like] |
| [Check 2] | `[command]` | [What success looks like] |
| [Check 3] | `[command]` | [What success looks like] |
**All checks pass?** You're done. Jump to [What's next](#-whats-next).
**Something failed?** See [Troubleshooting](#-troubleshooting) below.
---
## 🔧 Troubleshooting
### "[Exact error message the reader will see]"
**Cause:** [What triggers this error — be specific]
**Fix:**
```bash
[exact commands to resolve]
```
**Verify the fix:**
```bash
[command to confirm the error is resolved]
```
---
### "[Another common error message]"
**Cause:** [What triggers this]
**Fix:**
1. [Step 1]
2. [Step 2]
3. Re-run the step that failed
---
### "[Third common issue — might not be an error message but a symptom]"
**Cause:** [What causes this behavior]
**Fix:**
[Solution with commands]
---
### Still stuck?
- **Search existing issues:** [docs/project/issues/](../../docs/project/issues/)
- **Ask for help:** [docs/project/kanban/](../../docs/project/kanban/)
- **File a bug:** [issue template](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
---
## 🚀 What's next
Now that you've completed this guide:
- **[Next tutorial]** — [What it covers and why you'd want to do it next](../workflow_guide.md)
- **[Reference docs]** — [Where to learn the full feature set](../markdown_style_guide.md)
- **[Advanced topic]** — [Deeper dive for when you're ready](../operational_readiness.md)
<details>
<summary><strong>📋 Quick reference card</strong></summary>
Key commands and values from this guide for future reference:
| Action | Command |
| -------------- | ----------- |
| [Start] | `[command]` |
| [Stop] | `[command]` |
| [Check status] | `[command]` |
| [View logs] | `[command]` |
| [Reset] | `[command]` |
</details>
---
## 🔗 References
- [Official documentation](https://example.com) — [Which section is most relevant]
- [Source repository](https://github.com/borealBytes) — [For bug reports and contributions]
---
_Last verified: [Date] on [OS/Platform version] · Maintained by [Team/Author]_

303
scientific-skills/markdown-mermaid-writing/templates/issue.md Normal file
View File

@@ -0,0 +1,303 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Issue Documentation Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Documenting bugs, feature requests, improvement proposals, incidents, or any trackable work item as a persistent markdown record. This file IS the issue — the full lifecycle from report through investigation, resolution, and lessons learned — in a format that's searchable, portable, and part of your codebase.
**Key features:** Classification with severity/priority, customer impact quantification, reproduction steps with expected vs actual, investigation log, resolution with root cause, acceptance criteria for feature requests, and SLA tracking.
**Philosophy:** This file is the source of truth for the issue — not GitHub Issues, not Jira, not Linear. Those platforms are notification and comment layers. The full lifecycle — report, investigation, root cause, fix, and lessons learned — lives HERE, committed to the repo.
An issue report is a contract between the reporter and the resolver. Vague issues get vague fixes. The best issue documents are so clear that anyone on the team — or any AI agent — could pick them up, understand the problem, and start working without asking a single clarifying question. Include everything. Assume the person reading this has zero prior context.
This is the [Everything is Code](../markdown_style_guide.md#-everything-is-code) philosophy: any agent or team member can find, read, and update issues with file access alone. No API, no tokens, no platform lock-in. `grep docs/project/issues/` beats searching Jira every time.
---
## File Convention
```
docs/project/issues/issue-00000456-fix-session-timeout-race.md
docs/project/issues/issue-00000457-add-csv-export-filtering.md
docs/project/issues/issue-00000458-improve-onboarding-copy.md
```
- **Directory:** `docs/project/issues/`
- **Naming:** `issue-` + issue number zero-padded to 8 digits + `-` + short lowercase hyphenated description
- **Cross-reference:** Link to the live issue tracker in the metadata table
---
## Template Variants
This template has two variants — use the section that matches your issue type:
- **[Bug report](#bug-report-template)** — Something is broken, behaving unexpectedly, or crashing
- **[Feature request](#feature-request-template)** — Something new that should exist
---
## Bug Report Template
---
# Issue-[NUMBER]: [Short Description of the Bug]
| Field | Value |
| ---------------------- | ------------------------------------------------------------------------------------------------- |
| **Issue** | `#NUMBER` (add tracker URL if your project uses one) |
| **Type** | 🐛 Bug |
| **Severity** | 🟢 Low / 🟡 Medium / 🔴 High / 💀 Critical |
| **Priority** | P0 / P1 / P2 / P3 |
| **Reporter** | [Name] |
| **Assignee** | [Name or Unassigned] |
| **Date reported** | [YYYY-MM-DD] |
| **Status** | [Open / In progress / Resolved / Closed / Won't fix] |
| **Users affected** | [Count or segment — e.g., "~2,000 free-tier users" / "All API consumers"] |
| **Revenue impact** | [None / Indirect / Direct — $N/day or N% of transactions] |
| **Resolved in** | [PR-#NUMBER](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md) or N/A |
| **Time to resolution** | [N hours / N days — from report to fix deployed] |
---
## 📋 Summary
[One paragraph: What's broken, who's affected, and how severe the impact is. Be specific — "Users can't log in" not "auth is broken."]
### Customer impact
| Dimension | Assessment |
| --------------------- | ------------------------------------------------------------------------- |
| **Who's affected** | [User segment, account type, region — be specific] |
| **How many** | [Count, percentage, or estimate — e.g., "~500 enterprise accounts"] |
| **Business impact** | [Revenue, SLA violation, churn risk, reputational — quantify if possible] |
| **Workaround exists** | [Yes — describe briefly / No] |
---
## 🔄 Reproduction Steps
### Environment
| Detail | Value |
| -------------------- | -------------------------------------------- |
| **Version / commit** | [App version, commit SHA, or deploy tag] |
| **Environment** | [Production / Staging / Local] |
| **OS / Browser** | [e.g., macOS 15.2, Chrome 122] |
| **Account type** | [Admin / Standard / Free tier — if relevant] |
### Steps to reproduce
1. [Exact step 1 — be precise: "Navigate to /settings/profile"]
2. [Exact step 2 — "Click the 'Save' button"]
3. [Exact step 3 — "Observe the error"]
**Reproducibility:** [Always / Intermittent (~N% of attempts) / Once]
### Expected behavior
[What should happen when following the steps above.]
### Actual behavior
[What actually happens. Include the exact error message, screenshot, or log output.]
```
[Paste exact error message or log output here]
```
Screenshot placeholder: `docs/project/issues/images/issue-NUMBER-screenshot.png`
### Workaround
[If users can work around this bug, describe how. If no workaround exists, state "None known." This helps support teams while the fix is in progress.]
---
## 🔍 Investigation
### Root cause
[What's actually causing the bug. Fill this in during investigation, not at report time.]
[If the root cause involves a data flow or logic issue, diagram it:]
```mermaid
flowchart TB
accTitle: Bug Root Cause Flow
accDescr: Diagram showing where the failure occurs in the normal processing path
input[📥 Input] --> process[⚙️ Process]
process --> check{🔍 Validation}
check -->|Pass| success[✅ Expected]
check -->|Fail| bug[❌ Bug occurs here]
classDef bugstyle fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
class bug bugstyle
```
### Investigation log
| Date | Who | Finding |
| ------ | ------ | --------------------- |
| [Date] | [Name] | [What was discovered] |
| [Date] | [Name] | [Next finding] |
<details>
<summary><strong>🔧 Technical Details</strong></summary>
[Stack traces, debug logs, database queries, config diffs — anything that supports the investigation but is too verbose for the main document.]
</details>
---
## ✅ Resolution
### Fix description
[What was changed to fix the bug. Link to the PR.]
**Fixed in:** [PR-#NUMBER](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md)
### Verification
- [ ] Fix verified in [environment]
- [ ] Regression test added
- [ ] No side effects observed
- [ ] Reporter confirmed fix
### Lessons learned
[What should change to prevent this class of bug? New test? Better validation? Monitoring alert? Process change?]
---
## 🔗 References
- [Related issues](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
- [Relevant documentation](https://example.com)
- [Monitoring dashboard or alert](https://example.com)
---
_Last updated: [Date]_
---
---
## Feature Request Template
---
# Issue-[NUMBER]: [Feature Title — What Should Exist]
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| **Issue** | `#NUMBER` (add tracker URL if your project uses one) |
| **Type** | ✨ Feature request |
| **Priority** | P0 / P1 / P2 / P3 |
| **Requester** | [Name or Team] |
| **Assignee** | [Name or Unassigned] |
| **Date requested** | [YYYY-MM-DD] |
| **Status** | [Proposed / Accepted / In progress / Shipped / Declined] |
| **Target release** | [Version, sprint, or quarter] |
| **Shipped in** | [PR-#NUMBER](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md) or N/A |
---
## 📋 Summary
### Problem statement
[What user problem or business need does this feature address? Who experiences this problem and how often? Include metrics if available.]
### Proposed solution
[High-level description of what you want built. Focus on the _what_ and _why_, not the _how_ — leave implementation details to the builder.]
### User story
> As a **[role]**, I want to **[action]** so that **[benefit]**.
---
## 🎯 Acceptance Criteria
The feature is complete when:
- [ ] [Specific, testable criterion — "User can export data as CSV from the dashboard"]
- [ ] [Another criterion — "Export includes all filtered results, not just the current page"]
- [ ] [Another criterion — "Download starts within 3 seconds for datasets under 10K rows"]
- [ ] [Non-functional — "Works on mobile viewport (375px+)"]
- [ ] [Documentation — "API endpoint documented in project docs"]
---
## 📐 Design
### User flow
```mermaid
flowchart TB
accTitle: Feature User Flow
accDescr: Step-by-step flow showing how a user interacts with the proposed feature
start([👤 User action]) --> step1[⚙️ System response]
step1 --> check{🔍 Condition?}
check -->|Yes| success[✅ Success path]
check -->|No| alt[🔄 Alternative path]
alt --> step1
success --> done([📤 Result delivered])
```
### Mockup / wireframe
[If visual, include a mockup or screenshot of the expected UI. If not visual, describe the expected behavior in detail.]
### Technical considerations
- **[Consideration 1]:** [Impact on existing architecture, data model, or APIs]
- **[Consideration 2]:** [Performance, scalability, or security implications]
- **[Consideration 3]:** [Dependencies on other features, services, or teams]
<details>
<summary><strong>📋 Implementation Notes</strong></summary>
[Deeper technical context for the implementer — suggested approach, relevant code paths, database schema changes, API contract, migration strategy. This saves the builder from discovery time.]
</details>
---
## 📊 Impact
| Dimension | Assessment |
| ------------------- | ------------------------------------------- |
| **Users affected** | [How many users / what segment] |
| **Revenue impact** | [Direct, indirect, or none] |
| **Effort estimate** | [T-shirt size: S / M / L / XL] |
| **Dependencies** | [Other features, teams, or services needed] |
### Success metrics
[How will you know this feature is successful after shipping? Be specific and measurable.]
- **[Metric 1]:** [Current baseline] → [Target] within [timeframe]
- **[Metric 2]:** [Current baseline] → [Target] within [timeframe]
---
## 🔗 References
- [User feedback or support tickets](https://example.com)
- [Competitive analysis](https://example.com)
- [Related feature requests](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
- [Design document or ADR](../adr/ADR-001-agent-optimized-documentation-system.md)
---
_Last updated: [Date]_

223
scientific-skills/markdown-mermaid-writing/templates/kanban.md Normal file
View File

@@ -0,0 +1,223 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Kanban Board Documentation Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Tracking work items, sprint boards, project task management, release planning, or any scenario where you need a persistent, markdown-based view of work status. This board IS the tracking system — a file in your repo that evolves with your codebase.
**Key features:** Visual Mermaid kanban diagram, work item tables with status tracking, WIP limits, blocked items, explicit Won't Do decisions, aging indicators, flow efficiency metrics, and historical throughput.
**Philosophy:** This board is a file. Modify it in your branch, merge it with your PR. The board evolves WITH the codebase — no external board tool required. Anyone with repo access sees the board, AI agents included.
A kanban board's job is to make work visible. This template serves two purposes: (1) a living board that gets updated as work progresses, and (2) a historical snapshot when archived. The Mermaid diagram gives the instant visual overview; the tables give the detail. Together they answer: What's being worked on? What's blocked? What's done? What's next?
When archived, the board becomes the historical record of what was worked on, what was blocked, and what was completed — all in git history, with full attribution and timestamps. This is the [Everything is Code](../markdown_style_guide.md#-everything-is-code) philosophy: project management data lives in the repo, versioned and portable.
---
## File Convention
```
docs/project/kanban/sprint-2026-w07-agentic-template-modernization.md
docs/project/kanban/release-v2.3.0-launch-readiness.md
docs/project/kanban/project-auth-migration-phase-1.md
```
- **Directory:** `docs/project/kanban/`
- **Naming:** Prefix with board scope (`sprint-`, `release-`, `project-`) + identifier + short lowercase hyphenated description
- **Archiving:** When a board is complete, keep it in place — it becomes the historical record
---
## The Template
Everything below the line is the template. Copy from here:
---
# [Board Name] — Kanban Board
_[Scope: Sprint W07 2026 / Release v2.3.0 / Project: Auth Migration]_
_[Team/Owner] · Last updated: [YYYY-MM-DD HH:MM]_
---
## 📋 Board Overview
**Period:** [Start date] → [End date]
**Goal:** [One sentence — what does "done" look like for this board?]
**WIP Limit:** [Max items in "In Progress" — e.g., 3 per person, 6 total]
### Visual board
_Kanban board showing current work distribution across backlog, in-progress, review, done, blocked, and Won't Do columns:_
```mermaid
kanban
Backlog
task1[🔧 Deploy monitoring]
task2[📝 Write API docs]
In Progress
task3[⚙️ Build user dashboard]
task4[🐛 Fix payment timeout]
In Review
task5[👀 Add export feature]
Done
task6[🚀 Set up CI pipeline]
task7[📊 Database migration]
Blocked
task8[⛔ Waiting for security approval]
Won't Do
task9[❌ Drop mobile support in this sprint]
```
> ⚠️ Always show all 6 columns — Even if a column has no items, include it with a placeholder. This makes the board structure explicit and ensures categories are never forgotten. Use a placeholder like [No items yet] when a column is empty.
---
## 🚦 Board Status
| Column | Count | WIP Limit | Status |
| ------------------ | ----- | --------- | ---------------------------------------------- |
| 📋 **Backlog** | [N] | — | [Notes] |
| 🔄 **In Progress** | [N] | [Limit] | [🟢 Under limit / 🟡 At limit / 🔴 Over limit] |
| 🔍 **In Review** | [N] | [Limit] | [Status] |
| ✅ **Done** | [N] | — | [This period] |
| 🚫 **Blocked** | [N] | — | [See blocked section below] |
| 🚫 **Won't Do** | [N] | — | [Explicitly declined with rationale] |
> ⚠️ **Always include all 6 columns** — Each column represents a workflow state. Even if count is 0, keep the row visible. This prevents categories from being overlooked.
---
## 📋 Backlog
_Prioritized top-to-bottom. Top items are next to be pulled. Include at least one placeholder item if empty._
| # | Item | Priority | Estimate | Assignee | Notes |
| --- | ----------------- | --------- | -------- | -------- | ----------------------- |
| 1 | [Work item title] | 🔴 High | [S/M/L] | [Person] | [Context or dependency] |
| 2 | [Work item title] | 🟡 Medium | [Size] | [Person] | [Notes] |
| | _[No items yet]_ | | | | |
---
## 🔄 In Progress
_Items currently being worked on. Include at least one placeholder item if empty._
| Item | Assignee | Started | Expected | Days in column | Aging | Status |
| ----------- | -------- | ------- | -------- | -------------- | ----- | ---------------- |
| [Work item] | [Person] | [Date] | [Date] | [N] | 🟢 | 🟢 On track |
| | | | | | | _[No items yet]_ |
> 💡 **Aging indicator:** 🟢 Under expected time · 🟡 At expected time · 🔴 Over expected time — items aging red need attention or re-scoping.
> ⚠️ **WIP limit:** [N] / [Limit]. [Under limit / At limit — pull more work / Over limit — finish something before starting new work]
---
## 🔍 In Review
_Items awaiting or in code review. Include at least one placeholder item if empty._
| Item | Author | Reviewer | PR | Days in review | Aging | Status |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------ | -------------- | ----- | ------------------------------------------------ |
| [Work item] | [Person] | [Person] | [#NNN](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md) | [N] | 🟢 | [Awaiting review / Changes requested / Approved] |
| | | | | | | _[No items yet]_ |
---
## ✅ Done
_Completed this period. Include at least one placeholder item if empty._
| Item | Assignee | Completed | Cycle time | PR |
| ----------- | -------- | --------- | ---------- | ------------------------------------------------------------------------------------ |
| [Work item] | [Person] | [Date] | [N days] | [#NNN](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md) |
| | | | | _[No items completed this period]_ |
---
## 🚫 Blocked
_Items that cannot proceed. Always include at least the placeholder — blocked items are high-signal and should never be hidden._
| Item | Assignee | Blocked since | Blocked by | Escalated to | Unblock action |
| ----------- | -------- | ------------- | ------------------------------------------------------- | ------------- | ---------------------- |
| [Work item] | [Person] | [Date] | [What's blocking — dependency, decision, external team] | [Person/team] | [What needs to happen] |
| | | | | | _[No blocked items]_ |
> 🔴 **[N] items blocked.** [Summary of what's needed to unblock them.]
---
## 🚫 Won't Do
_Explicitly out of scope for this board period. Capture rationale so these decisions are transparent and auditable. Include placeholder if empty._
| Item | Date decided | Decision owner | Rationale | Revisit trigger |
| ----------- | ------------ | -------------- | ---------------------------------------------- | ------------------------------------ |
| [Work item] | [Date] | [Person/team] | [Why this is intentionally excluded right now] | [What change would reopen this item] |
| | | | _[No items explicitly declined]_ | |
---
## 📊 Metrics
### This period
| Metric | Value | Target | Trend |
| ---------------------------------- | -------- | -------- | ------- |
| **Throughput** (items completed) | [N] | [Target] | [↑/→/↓] |
| **Avg cycle time** (start → done) | [N days] | [Target] | [↑/→/↓] |
| **Avg lead time** (created → done) | [N days] | [Target] | [↑/→/↓] |
| **Avg review time** | [N days] | [Target] | [↑/→/↓] |
| **Flow efficiency** | [N%] | [Target] | [↑/→/↓] |
| **Blocked items** | [N] | 0 | [↑/→/↓] |
| **WIP limit breaches** | [N] | 0 | [↑/→/↓] |
| **Items aging red** | [N] | 0 | [↑/→/↓] |
> 💡 **Flow efficiency** = active work time ÷ total cycle time × 100. A healthy team targets 40%+. Below 15% means items spend most of their time waiting, not being worked on.
<details>
<summary><strong>📊 Historical Throughput</strong></summary>
| Period | Items completed | Avg cycle time | Blocked days |
| ------------------- | --------------- | -------------- | ------------ |
| [Previous period 3] | [N] | [N days] | [N] |
| [Previous period 2] | [N] | [N days] | [N] |
| [Previous period 1] | [N] | [N days] | [N] |
| **Current** | [N] | [N days] | [N] |
</details>
---
## 📝 Board Notes
### Decisions made this period
- **[Date]:** [Decision and context — e.g., "Deprioritized auth refactor to focus on payment bug"]
- **[Date]:** [Added/updated Won't Do decision with explicit rationale and revisit trigger]
### Carryover from last period
- [Item carried over] — [Why it wasn't completed and current status]
### Upcoming dependencies
- [Date]: [External dependency, release, or event that affects this board]
---
## 🔗 References
- [Live project board](../../docs/project/kanban/sprint-2026-w08-crewai-review-hardening-and-memory.md) — Real-time tracking
- [Previous board](../../docs/project/kanban/sprint-2026-w07-agentic-template-modernization.md) — Last period's snapshot
- [Status report](../../docs/project/pr/pr-00000001-agentic-docs-and-monorepo-modernization.md) — Executive summary of this period
---
_Next update: [Date] · Board owner: [Person/Team]_

312
scientific-skills/markdown-mermaid-writing/templates/presentation.md Normal file
View File

@@ -0,0 +1,312 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Presentation / Briefing Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Slide-deck-style documents, research presentations, briefings, lectures, walkthroughs, or any content that would traditionally be a PowerPoint. Designed to read well as a standalone document AND to serve as speaker-ready presentation notes.
**Key features:** Collapsible speaker notes under every section, structured flow from context through content to action items, figure captions, and footnote citations.
---
## How to Use
1. Copy this file to your project
2. Replace all `[bracketed placeholders]` with your content
3. Delete sections that don't apply (but keep the core flow)
4. Add/remove content topics (H3s under 📚 Content) as needed
5. Follow the [Markdown Style Guide](../markdown_style_guide.md) for all formatting
6. Add [Mermaid diagrams](../mermaid_style_guide.md) wherever a concept benefits from a visual
---
## Template Structure
The presentation follows a 6-section flow. Each section has an H2 with one emoji, content, and optional collapsible speaker notes.
```
1. 🏠 Housekeeping — Logistics, context, announcements
2. 📍 Agenda — What we'll cover, with time estimates
3. 🎯 Objectives — What the audience will walk away with
4. 📚 Content — The main body (multiple H3 topics)
5. ✍️ Action Items — What happens next, who owns what
6. 🔗 References — Citations, resources, further reading
```
---
## The Template
Everything below the line is the template. Copy from here:
---
# [Presentation Title]
_[Context line — project, team, date, or purpose]_
---
## 🏠 Housekeeping
- [Logistics item or announcement]
- [Important deadline or reminder]
- [Any prerequisite context the audience needs]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- **Timing:** 2–3 minutes for this section
- **Tone:** Conversational, get the room settled
- [Specific note about announcement context]
- [Transition line:] "With that covered, here's our plan for today..."
</details>
---
## 📍 Agenda
- [x] Housekeeping (3 min)
- [ ] [Topic 1 name] (10 min)
- [ ] [Topic 2 name] (15 min)
- [ ] [Topic 3 name] (15 min)
- [ ] Action items and Q&A (10 min)
**Total:** [estimated time]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- Reference this agenda when transitioning between topics
- If running long on a topic, note what you'll compress
- "We have a natural break around the halfway point"
- Adjust timing based on audience engagement — questions are good
</details>
---
## 🎯 Objectives
After this presentation, you'll be able to:
- **[Action verb]** [specific, measurable outcome]
- **[Action verb]** [specific, measurable outcome]
- **[Action verb]** [specific, measurable outcome]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- Reference these objectives throughout the presentation
- "This connects back to our first objective..."
- At the end, revisit: "Let's check — did we hit all three?"
- **Strong action verbs:** Identify, Analyze, Compare, Evaluate, Design, Implement, Explain, Distinguish, Create, Apply
</details>
---
## 📚 Content
### [Topic 1 title]
[Opening context — why this matters, what problem it solves]
**Key points:**
- [Point 1 with brief explanation]
- [Point 2 with brief explanation]
- [Point 3 with brief explanation]
Image placeholder: `images/slide-[filename].png`
_Figure 1: [What this image demonstrates]_
> 💡 **Key insight:** [The one-liner the audience should remember from this topic]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
### Teaching strategy
- **Open with a question:** "[Engaging question for the audience]?"
- Take 2–3 responses
- "Good thinking. Here's how this actually works..."
### Core explanation (3–5 min)
- Start with the definition/concept
- Walk through step by step
- Use a real-world example: "[Specific scenario]"
### Common misconceptions
- **What people think:** [Misconception]
- **What's actually true:** [Reality]
- **How to address it:** [Reframe]
### Transition
- "Now that we understand [concept], let's look at how it applies to..."
</details>
---
### [Topic 2 title]
[Context and explanation]
**Comparison of approaches:**
| Approach | Best for | Tradeoffs |
| ---------- | ---------- | --------- |
| [Option A] | [Scenario] | [Pro/con] |
| [Option B] | [Scenario] | [Pro/con] |
| [Option C] | [Scenario] | [Pro/con] |
```mermaid
flowchart LR
accTitle: [Short title for this diagram]
accDescr: [One sentence describing what the diagram shows]
step1[⚙️ Step one] --> step2[🔍 Step two] --> step3[✅ Step three]
```
[Explanation of what the diagram shows and why it matters]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
### Walk through each option (5–6 min)
**Option A:**
- "Used when [scenario]"
- "Advantage: [benefit]"
- "Disadvantage: [drawback]"
**Option B:**
- "Used when [scenario]"
- "Advantage: [benefit]"
- "Disadvantage: [drawback]"
### Decision-making exercise
- Ask: "Given [scenario], which would you choose?"
- Take responses, discuss reasoning
- "In practice, professionals choose based on [criteria]"
### Real-world example
- "[Company/project] chose Option B because [reasoning]"
- "The result was [outcome]"
- "This matters because [relevance to audience]"[^1]
</details>
---
### [Topic 3 title]
[Context and explanation]
**Process:**
1. [First step with explanation]
2. [Second step with explanation]
3. [Third step with explanation]
> ⚠️ **Common pitfall:** [What goes wrong and how to avoid it]
[Deeper explanation, examples, or data supporting the topic]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
### Interactive element
- Pause at step 2: "What happens next?"
- Take guesses before revealing step 3
- "Why does this matter? Because [stakes]"
### If audience is advanced
- Skip the basics, jump to: "[Advanced angle]"
- Challenge question: "What if [scenario changed]?"
### If audience is struggling
- Slow down, repeat the analogy
- "Think of it like [simple comparison]"
- Offer to cover more in Q&A
### Timing
- This should take about [N] minutes
- If running long, compress the [specific part]
</details>
---
## ✍️ Action items
### Next steps
| Action | Owner | Due |
| ---------------------- | ------------- | ------ |
| [Specific action item] | [Person/team] | [Date] |
| [Specific action item] | [Person/team] | [Date] |
| [Specific action item] | [Person/team] | [Date] |
### Key takeaways
1. **[Takeaway 1]** — [one sentence summary]
2. **[Takeaway 2]** — [one sentence summary]
3. **[Takeaway 3]** — [one sentence summary]
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- Walk through each action item explicitly
- "Who owns this? When is it due?"
- "Questions about any of these?"
- Revisit the objectives: "Did we hit all three?"
- "Thank you for your time. I'm available for follow-up at [contact]."
</details>
---
## 🔗 References
### Sources cited
_All footnote references from the presentation are collected here:_
[^1]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
### Further reading
- [Resource title](https://example.com) — Why this is useful
- [Resource title](https://example.com) — What it provides
### Tools mentioned
- [Tool name](https://example.com) — Purpose and how to access
<details>
<summary><strong>💬 Speaker Notes</strong></summary>
- "These resources are available in the shared document"
- "Start with [specific resource] — it's the most practical"
- "If you want to go deeper, [specific resource] covers the advanced topics"
</details>
---
_Last updated: [Date]_

412
scientific-skills/markdown-mermaid-writing/templates/project_documentation.md Normal file
View File

@@ -0,0 +1,412 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Project Documentation Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Software projects, open-source libraries, internal tools, APIs, platforms, or any product that needs documentation for users and contributors. Designed to take someone from "what is this?" to "I'm contributing" in a single read.
**Key features:** Quick start that gets people running in under 5 minutes, architecture overview with Mermaid diagrams, API reference structure, troubleshooting section that addresses real problems, and contribution guidelines.
**Philosophy:** The best project docs eliminate the need to read the source code to understand the system. A new team member should be productive in hours, not weeks. Every "how does this work?" question should have an answer in this document or be one click away.
---
## How to Use
1. Copy this file as your project's main `README.md` or `docs/index.md`
2. Replace all `[bracketed placeholders]` with your content
3. Delete sections that don't apply (a CLI tool might skip API reference; a library might skip deployment)
4. Add [Mermaid diagrams](../mermaid_style_guide.md) — especially for architecture, data flow, and request lifecycle
5. Keep the Quick Start brutally simple — if setup takes more than 5 commands, simplify it
---
## The Template
Everything below the line is the template. Copy from here:
---
# [Project Name]
[One sentence: what this does and why someone would use it.]
[One sentence: the key differentiator or value proposition.]
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]() [![License](https://img.shields.io/badge/license-MIT-blue)]()
---
## 📋 Table of contents
- [Quick start](#-quick-start)
- [Architecture](#-architecture)
- [Configuration](#-configuration)
- [API reference](#-api-reference)
- [Deployment](#-deployment)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [References](#-references)
---
## 🚀 Quick start
### Prerequisites
| Requirement | Version | Check command |
| ------------------ | ----------- | --------------------- |
| [Runtime/Language] | ≥ [version] | `[command] --version` |
| [Database/Service] | ≥ [version] | `[command] --version` |
| [Tool] | ≥ [version] | `[command] --version` |
### Install and run
```bash
# Clone the repository
git clone https://github.com/[org]/[repo].git
cd [repo]
# Install dependencies
[package-manager] install
# Configure environment
cp .env.example .env
# Edit .env with your values
# Start the application
[package-manager] run dev
```
**Verify it works:**
```bash
curl http://localhost:[port]/health
# Expected: {"status": "ok", "version": "[version]"}
```
> 💡 **First-time setup issues?** See [Troubleshooting](#-troubleshooting) for common problems.
---
## 🏗️ Architecture
### System overview
[2–3 sentences explaining the high-level architecture — what the major components are and how they interact.]
```mermaid
flowchart TB
accTitle: System Architecture Overview
accDescr: High-level architecture showing client, API, services, and data layers with primary data flow paths
client([👤 Client]) --> api[🌐 API Gateway]
subgraph services ["⚙️ Services"]
svc_a[📋 Service A]
svc_b[📦 Service B]
svc_c[🔐 Auth Service]
end
subgraph data ["💾 Data"]
db[(💾 Primary DB)]
cache[⚡ Cache]
queue[📥 Message Queue]
end
api --> svc_c
api --> svc_a
api --> svc_b
svc_a --> db
svc_a --> cache
svc_b --> queue
svc_b --> db
classDef svc fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef data fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class svc_a,svc_b,svc_c svc
class db,cache,queue data
```
### Key components
| Component | Purpose | Technology |
| ------------- | -------------- | ------------ |
| [Component 1] | [What it does] | [Tech stack] |
| [Component 2] | [What it does] | [Tech stack] |
| [Component 3] | [What it does] | [Tech stack] |
### Data flow
[Describe the primary request lifecycle — what happens when a user makes a typical request.]
```mermaid
sequenceDiagram
accTitle: Primary Request Lifecycle
accDescr: Sequence showing how a typical request flows through the API gateway, service layer, and data stores
participant C as 👤 Client
participant A as 🌐 API Gateway
participant S as ⚙️ Service
participant D as 💾 Database
C->>A: 📤 Request
A->>A: 🔐 Authenticate
A->>S: ⚙️ Process
S->>D: 🔍 Query
D-->>S: 📥 Results
S-->>A: 📤 Response
A-->>C: ✅ 200 OK
```
<details>
<summary><strong>📋 Detailed Architecture Notes</strong></summary>
### Directory structure
```
[repo]/
├── src/
│ ├── api/ # Route handlers and middleware
│ ├── services/ # Business logic
│ ├── models/ # Data models and schemas
│ ├── config/ # Configuration and environment
│ └── utils/ # Shared utilities
├── tests/
│ ├── unit/
│ └── integration/
├── docs/ # Additional documentation
└── scripts/ # Build, deploy, and maintenance scripts
```
### Design decisions
- **[Decision 1]:** [Why this approach was chosen over alternatives. Link to ADR if one exists.]
- **[Decision 2]:** [Why this approach was chosen.]
</details>
---
## ⚙️ Configuration
### Environment variables
| Variable | Required | Default | Description |
| -------------- | -------- | ---------------- | --------------------------------------------------- |
| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
| `REDIS_URL` | No | `localhost:6379` | Redis cache connection |
| `LOG_LEVEL` | No | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |
| `PORT` | No | `3000` | HTTP server port |
| `[VAR_NAME]` | [Yes/No] | [default] | [Description] |
### Configuration files
| File | Purpose |
| ------------------------ | --------------------------------------------- |
| `.env` | Local environment variables (never committed) |
| `config/default.json` | Default settings for all environments |
| `config/production.json` | Production overrides |
---
## 📡 API Reference
### Authentication
All API requests require a bearer token in the `Authorization` header:
```
Authorization: Bearer <token>
```
Obtain a token via `POST /auth/login`. Tokens expire after [duration].
### Endpoints
#### `GET /api/[resource]`
**Description:** [What this endpoint returns]
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ----------------------------------- |
| `limit` | integer | No | Max results (default: 20, max: 100) |
| `offset` | integer | No | Pagination offset |
| `[param]` | [type] | [Yes/No] | [Description] |
**Response:**
```json
{
"data": [
{
"id": "uuid",
"name": "Example",
"created_at": "2026-01-15T10:30:00Z"
}
],
"meta": {
"total": 42,
"limit": 20,
"offset": 0
}
}
```
**Error responses:**
| Status | Meaning | When |
| ------ | ------------ | ---------------------------- |
| `401` | Unauthorized | Missing or invalid token |
| `403` | Forbidden | Insufficient permissions |
| `404` | Not found | Resource doesn't exist |
| `429` | Rate limited | Exceeded [N] requests/minute |
<details>
<summary><strong>📡 Additional Endpoints</strong></summary>
#### `POST /api/[resource]`
[Request body, parameters, response format]
#### `PUT /api/[resource]/:id`
[Request body, parameters, response format]
#### `DELETE /api/[resource]/:id`
[Parameters, response format]
</details>
---
## 🚀 Deployment
### Production deployment
```bash
# Build
[package-manager] run build
# Run database migrations
[package-manager] run migrate
# Start production server
[package-manager] run start
```
### Environment requirements
| Requirement | Production | Staging |
| ----------- | ---------- | ------- |
| CPU | [spec] | [spec] |
| Memory | [spec] | [spec] |
| Storage | [spec] | [spec] |
| Database | [spec] | [spec] |
### Health checks
| Endpoint | Expected | Purpose |
| ------------------- | -------- | ---------------------------------------- |
| `GET /health` | `200 OK` | Basic liveness |
| `GET /health/ready` | `200 OK` | Full readiness (DB, cache, dependencies) |
<details>
<summary><strong>🔧 CI/CD Pipeline Details</strong></summary>
[Describe the deployment pipeline — build steps, test stages, deployment targets, rollback procedures.]
</details>
---
## 🔧 Troubleshooting
### Common issues
#### "Connection refused" on startup
**Cause:** Database is not running or connection string is incorrect.
**Fix:**
1. Verify database is running: `[check-command]`
2. Check `DATABASE_URL` in `.env`
3. Test connection: `[test-command]`
#### "[Specific error message]"
**Cause:** [What triggers this error]
**Fix:**
1. [Step 1]
2. [Step 2]
#### Slow response times
**Cause:** [Common causes — missing indexes, cache cold start, etc.]
**Fix:**
1. Check cache connectivity: `[command]`
2. Verify database indexes: `[command]`
3. Review recent changes to query patterns
### Getting help
- **Bug reports:** [Link to issue template or process]
- **Questions:** [Link to discussions, Slack channel, or forum]
- **Security issues:** [Email or private disclosure process]
---
## 🤝 Contributing
### Development setup
```bash
# Fork and clone
git clone https://github.com/[your-fork]/[repo].git
# Install with dev dependencies
[package-manager] install --dev
# Run tests
[package-manager] test
# Run linter
[package-manager] run lint
```
### Workflow
1. Create a branch from `main`: `git checkout -b feature/your-feature`
2. Make changes following the code style (enforced by linter)
3. Write tests for new functionality
4. Run the full test suite: `[package-manager] test`
5. Open a pull request with a clear description
### Code standards
- [Language/framework style guide or linter config]
- [Test coverage expectations]
- [PR review process]
- [Documentation expectations for new features]
---
## 🔗 References
- [Official framework docs](https://example.com) — [What version and which sections are most relevant]
- [API specification](https://example.com) — [OpenAPI/Swagger link if applicable]
- [Architecture Decision Records](../adr/) — [Why key decisions were made]
---
_Last updated: [Date] · Maintained by [Team/Owner]_

319
scientific-skills/markdown-mermaid-writing/templates/pull_request.md Normal file
View File

@@ -0,0 +1,319 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Pull Request Documentation Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Documenting pull requests as persistent, searchable markdown records. This file IS the PR — not a companion document. It captures everything: what changed, why, how to verify, security impact, deployment strategy, and what was learned.
**Key features:** Summary with impact classification, change inventory with before/after, testing evidence, security review, breaking change documentation, deployment strategy, observability plan, rollback plan, and reviewer checklist.
**Philosophy:** This file IS the PR description — not a companion, not a supplement, not a copy. The GitHub PR is a thin pointer: humans go there to comment on diffs, approve, and watch CI. But the actual record — what changed, why it changed, testing evidence, rollback plan, and lessons learned — lives HERE, committed to the repo.
When someone asks "what was PR #123 about?" six months from now, they `grep docs/project/pr/`, not the GitHub API. When you migrate from GitHub to GitLab, every PR record comes with you. When an AI agent needs to understand the history of a module, it reads these files locally — no tokens, no rate limits, no platform dependency.
This is the [Everything is Code](../markdown_style_guide.md#-everything-is-code) philosophy: project management data lives in the repo, versioned and portable. Don't capture information in GitHub's UI that should be captured in this file. Invest the 10 minutes. A great PR file eliminates the "what was this PR about?" Slack message and the "can someone check the GitHub PR?" context switch — the answer is already in the repo.
---
## File Convention
```
docs/project/pr/pr-00000123-fix-auth-timeout.md
docs/project/pr/pr-00000124-add-job-retry-metrics.md
docs/project/pr/pr-00000125-refactor-ci-stage-order.md
```
- **Directory:** `docs/project/pr/`
- **Naming:** `pr-` + PR number zero-padded to 8 digits + `-` + short lowercase hyphenated description
- **Cross-reference:** Link to the live PR in the metadata table
- **GitHub PR body:** Use only the full branch URL to this file (for example, `https://github.com/<org>/<repo>/blob/<branch>/docs/project/pr/pr-00000123-fix-auth-timeout.md`)
---
## The Template
Everything below the line is the template. Copy from here:
---
# PR-[NUMBER]: [Concise Title — What This Changes]
| Field | Value |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PR** | `#NUMBER` (add tracker URL if your project uses one) |
| **Author** | [Name] |
| **Date** | [YYYY-MM-DD] |
| **Status** | [Open / Merged / Closed] |
| **Branch** | `[feature/branch-name]` → `main` |
| **Related issues** | [#ISSUE](../../docs/project/issues/issue-00000001-agentic-documentation-system.md), [#ISSUE2](../../docs/project/issues/issue-00000002-provider-priority-fail-fast-review-cost-visibility.md) |
| **Deploy strategy** | [Standard / Canary / Blue-green / Feature flag] |
---
## 📋 Summary
### What changed and why
[2–4 sentences. What this PR does at a business/product level, not code level. Why was this change necessary? What problem does it solve or what feature does it enable?]
### Impact classification
| Dimension | Level | Notes |
| ----------------- | ------------------------------------------------------- | ------------------------------------- |
| **Risk** | 🟢 Low / 🟡 Medium / 🔴 High | [Why this risk level] |
| **Scope** | [Narrow / Moderate / Broad] | [What areas are affected] |
| **Reversibility** | [Easily reversible / Requires migration / Irreversible] | [Rollback complexity] |
| **Security** | [None / Low / Medium / High] | [Auth, data, or permissions changes?] |
---
## 🔍 Changes
### Change inventory
| File / Area | Change type | Description |
| ---------------- | -------------------------------------- | ---------------------- |
| `[path/to/file]` | [Added / Modified / Deleted / Renamed] | [What changed and why] |
| `[path/to/file]` | [Type] | [Description] |
| `[path/to/file]` | [Type] | [Description] |
### Before and after
[For behavioral changes, show the difference. Use code blocks, screenshots, or diagrams as appropriate.]
**Before:**
```
[Previous behavior, output, or code pattern]
```
**After:**
```
[New behavior, output, or code pattern]
```
### Architecture impact
[If this PR changes how components interact, include a diagram. Skip this section for small changes.]
```mermaid
flowchart LR
accTitle: Architecture Change
accDescr: How this PR modifies the component interaction pattern
a[⚙️ Component A] -->|New path| b[📦 Component B]
b --> c[💾 Data Store]
```
<details>
<summary><strong>📋 Detailed Change Notes</strong></summary>
[Extended context for complex PRs — design tradeoffs, alternative approaches considered, migration details, performance benchmarks, or anything that helps reviewers understand the depth of the change.]
</details>
---
## 🧪 Testing
### How to verify
```bash
# Steps a reviewer can follow to test this change locally
[command 1]
[command 2]
[command 3 — with expected output]
```
### Test coverage
| Test type | Status | Notes |
| ----------------- | ----------- | ---------------------------------- |
| Unit tests | ✅ Passing | [N new / N modified] |
| Integration tests | ✅ Passing | [Details] |
| Manual testing | ✅ Verified | [What was tested manually] |
| Performance | ⬜ N/A | [Or benchmark results if relevant] |
### Edge cases considered
- [Edge case 1 — how it's handled]
- [Edge case 2 — how it's handled]
- [Edge case 3 — or "not applicable" for this change]
---
## 🔒 Security
### Security checklist
- [ ] No secrets, credentials, API keys, or PII in the diff
- [ ] Authentication/authorization changes reviewed (if applicable)
- [ ] Input validation added for new user-facing inputs
- [ ] Injection protections maintained (SQL, XSS, CSRF)
- [ ] Dependencies scanned for known vulnerabilities
- [ ] Data encryption at rest/in transit maintained
**Security impact:** [None / Low / Medium / High] — [Brief justification]
[If security-sensitive: **Reviewed by:** [security reviewer name, date]]
<details>
<summary><strong>🔐 Security Details</strong></summary>
[For security-sensitive changes: threat model, attack vectors considered, mitigations applied. This section helps future security audits understand what was evaluated.]
</details>
---
## ⚡ Breaking Changes
**This PR introduces breaking changes:** [Yes / No]
[If no, delete the rest of this section.]
### What breaks
| What breaks | Who's affected | Migration path |
| ---------------------------------- | ------------------------ | ---------------- |
| [API endpoint / behavior / config] | [Service / team / users] | [How to migrate] |
### Migration guide
**Before:**
```
[Old usage, API call, config, or behavior]
```
**After:**
```
[New usage — what consumers need to change]
```
**Deprecation timeline:** [When the old behavior will be removed, if applicable]
---
## 🔄 Rollback Plan
[How to revert this change if something goes wrong in production.]
**Revert command:**
```bash
git revert [commit-sha]
```
**Additional steps needed:**
- [ ] [Database migration rollback if applicable]
- [ ] [Feature flag disable if applicable]
- [ ] [Cache invalidation if applicable]
- [ ] [Notify affected teams]
> ⚠️ **Rollback risk:** [Any caveats — data migration that's one-way, API consumers that may have adopted the new contract, etc.]
---
## 🚀 Deployment
### Strategy
**Approach:** [Standard deploy / Canary (N% → 100%) / Blue-green / Feature flag]
**Feature flags:** [Flag name: `[flag_name]` — default: [off/on], rollout: [%/audience]]
### Pre-deployment
- [ ] [Database migrations applied]
- [ ] [Environment variables set]
- [ ] [Dependent services deployed first: [service names]]
- [ ] [Feature flag configured in [flag management tool]]
### Post-deployment verification
- [ ] [Health check endpoint returns 200]
- [ ] [Key user flow verified: [which flow]]
- [ ] [Metrics baseline captured: [which metrics]]
- [ ] [No error rate spike in first [N] minutes]
---
## 📡 Observability
### Monitoring
- **Dashboard:** [Link to relevant dashboard or "existing dashboards sufficient"]
- **Key metrics to watch:** [Latency p95, error rate, throughput — be specific]
- **Watch window:** [How long to monitor post-deploy: 15m / 1h / 24h]
### Alerts
- [New alerts added: [alert name, threshold, channel]]
- [Existing alerts affected: [which ones and how]]
- [Or: "No alert changes needed"]
### Logging
- [New log entries: [what's logged, at what level]]
- [Changed log levels: [what changed and why]]
- [Or: "No logging changes"]
### Success criteria
[How do you know this deploy is healthy? Be specific: "p95 latency stays under 200ms, error rate stays below 0.1%, no new error types in logs for 1 hour."]
---
## ✅ Reviewer Checklist
- [ ] Code follows project style guide and linting rules
- [ ] No `TODO` or `FIXME` comments introduced without linked issues
- [ ] Error handling covers failure modes (no empty catch blocks)
- [ ] No secrets, credentials, or PII in the diff
- [ ] Tests cover the happy path and at least one error path
- [ ] Documentation updated if public API or behavior changed
- [ ] Database migrations are reversible (if applicable)
- [ ] Performance impact considered (no N+1 queries, no unbounded lists)
- [ ] Breaking changes documented with migration guide (if applicable)
- [ ] Feature flag configured correctly (if applicable)
- [ ] Monitoring/alerting updated for new failure modes (if applicable)
- [ ] Security review completed (if security-sensitive)
---
## 💬 Discussion
[Capture key review feedback and decisions made during the review process. This is the institutional memory — future developers will read this.]
### Release note
**Category:** [Feature / Fix / Enhancement / Breaking / Security / Performance]
> [One-line release note for changelog — written for end users, not developers]
### Key review decisions
- **[Topic]:** [What was discussed and what was decided]
- **[Topic]:** [Discussion and resolution]
### Follow-up items
- [ ] [Task that should happen after merge but isn't blocking](../../docs/project/issues/issue-00000003-local-review-context-pack-and-resilience.md)
- [ ] [Technical debt to address later](../../docs/project/issues/issue-00000004-memory-backend-self-hosted-and-sql-seed.md)
---
## 🔗 References
- [Design document or ADR](../adr/ADR-001-agent-optimized-documentation-system.md)
- [Related issue](../../docs/project/issues/issue-00000001-agentic-documentation-system.md)
- [Relevant documentation](https://example.com)
---
_Last updated: [Date]_

304
scientific-skills/markdown-mermaid-writing/templates/research_paper.md Normal file
View File

@@ -0,0 +1,304 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Research Paper / Technical Analysis Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Research papers, technical analyses, literature reviews, data-driven reports, competitive analyses, market research, or any document built around evidence and methodology. Designed for heavy citation, structured argumentation, and reproducible findings.
**Key features:** Abstract for quick assessment, methodology section for credibility, findings with supporting data/diagrams, rigorous footnote citations throughout, and a complete references section.
**Philosophy:** A great research document lets the reader evaluate your conclusions independently. Show your work. Cite your sources. Present counter-arguments. The reader should trust your findings because the evidence is right there — not because you said so.
---
## How to Use
1. Copy this file to your project
2. Replace all `[bracketed placeholders]` with your content
3. Adjust sections — not every paper needs every section, but the core flow (Abstract → Introduction → Methodology → Findings → Conclusion) should stay intact
4. **Cite aggressively** — every claim, every statistic, every external methodology reference gets a `[^N]` footnote
5. Add [Mermaid diagrams](../mermaid_style_guide.md) for any process, architecture, data flow, or comparison
---
## Template Structure
```
1. Abstract — What you did, what you found, why it matters (150-300 words)
2. 📋 Introduction — Problem statement, context, scope, research questions
3. 📚 Background — Prior work, literature review, industry context
4. 🔬 Methodology — How you did the research, data sources, approach
5. 📊 Findings — What you discovered, with evidence and diagrams
6. 💡 Analysis — What the findings mean, implications, limitations
7. 🎯 Conclusions — Summary, recommendations, future work
8. 🔗 References — All cited sources with full URLs
```
---
## The Template
Everything below the line is the template. Copy from here:
---
# [Paper Title: Descriptive and Specific]
_[Author(s) or Team] · [Organization] · [Date]_
---
## Abstract
[150–300 word summary structured as: **Context** (1–2 sentences on the problem space), **Objective** (what this paper investigates), **Method** (how the research was conducted), **Key findings** (the most important results), **Significance** (why this matters and who should care).]
**Keywords:** [keyword 1], [keyword 2], [keyword 3], [keyword 4], [keyword 5]
---
## 📋 Introduction
### Problem statement
[What problem exists? Why does it matter? Who is affected? Be specific — include metrics where available.]
[The scope of the problem, with citation][^1].
### Research questions
This paper investigates:
1. **[RQ1]** — [Specific, answerable question]
2. **[RQ2]** — [Specific, answerable question]
3. **[RQ3]** — [Specific, answerable question]
### Scope and boundaries
- **In scope:** [What this paper covers]
- **Out of scope:** [What this paper deliberately excludes and why]
- **Target audience:** [Who will benefit from these findings]
<details>
<summary><strong>💬 Context Notes</strong></summary>
- Why this research was initiated
- Organizational context or business driver
- Relationship to prior internal work
- Known constraints that shaped the scope
</details>
---
## 📚 Background
### Industry context
[Current state of the field. What's known. What the established approaches are. Cite existing work.]
[Key finding from prior research][^2]. [Another relevant study found][^3].
### Prior work
| Study / Source | Key Finding | Relevance to Our Work |
| ------------------- | ----------------- | --------------------- |
| [Author (Year)][^4] | [What they found] | [How it connects] |
| [Author (Year)][^5] | [What they found] | [How it connects] |
| [Author (Year)][^6] | [What they found] | [How it connects] |
### Gap in current knowledge
[What's missing from existing research? What question remains unanswered? This is the gap your paper fills.]
<details>
<summary><strong>📋 Extended Literature Review</strong></summary>
[Deeper discussion of related work, historical context, evolution of approaches, and detailed comparison of methodologies used by prior researchers. This depth supports the paper's credibility without cluttering the main flow.]
</details>
---
## 🔬 Methodology
### Approach
[Describe your research methodology — qualitative, quantitative, mixed methods, experimental, observational, case study, etc.]
```mermaid
flowchart LR
accTitle: Research Methodology Flow
accDescr: Four-phase research process from data collection through analysis to validation and reporting
collect[📥 Data **collection**] --> clean[⚙️ Data **cleaning**]
clean --> analyze[🔍 **Analysis**]
analyze --> validate[🧪 **Validation**]
validate --> report[📤 Report **findings**]
classDef process fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
class collect,clean,analyze,validate,report process
```
### Data sources
| Source | Type | Size / Scope | Collection Period |
| ---------- | -------------------------------- | ------------------------- | ----------------- |
| [Source 1] | [Survey / API / Database / etc.] | [N records / respondents] | [Date range] |
| [Source 2] | [Type] | [Size] | [Date range] |
### Tools and technologies
- **[Tool 1]** — [Purpose and version]
- **[Tool 2]** — [Purpose and version]
- **[Analysis framework]** — [Why this was chosen]
### Limitations of methodology
> ⚠️ **Known limitations:** [Be upfront about what could affect the validity of your results — sample size, selection bias, time constraints, data quality issues. This builds credibility, not weakness.]
<details>
<summary><strong>🔧 Detailed Methodology</strong></summary>
### Data collection protocol
[Step-by-step description of how data was gathered]
### Cleaning and preprocessing
[What transformations were applied, what was excluded and why]
### Statistical methods
[Specific tests, confidence levels, software used]
### Reproducibility
[How someone else could replicate this research — data availability, code repositories, environment setup]
</details>
---
## 📊 Findings
### Finding 1: [Descriptive title]
[Present the finding clearly. Lead with the conclusion, then show the evidence.]
[Data supporting this finding][^7]:
| Metric | Before | After | Change |
| ---------- | ------- | ------- | ------- |
| [Metric 1] | [Value] | [Value] | [+/- %] |
| [Metric 2] | [Value] | [Value] | [+/- %] |
> 📌 **Key insight:** [One-sentence takeaway from this finding]
### Finding 2: [Descriptive title]
[Present the finding. Include a diagram if the finding involves relationships, processes, or comparisons.]
```mermaid
xychart-beta
title "[Chart title]"
x-axis ["Category A", "Category B", "Category C", "Category D"]
y-axis "Measurement" 0 --> 100
bar [45, 72, 63, 89]
```
[Explanation of what the data shows and why it matters.]
### Finding 3: [Descriptive title]
[Present the finding with supporting evidence.]
<details>
<summary><strong>📊 Supporting Data Tables</strong></summary>
[Detailed data tables, raw numbers, statistical breakdowns that support the findings but would interrupt the reading flow if placed inline. Readers who want to verify can expand.]
</details>
---
## 💡 Analysis
### Interpretation
[What do the findings mean? Connect back to your research questions. Explain the "so what?"]
- **RQ1:** [How Finding 1 answers Research Question 1]
- **RQ2:** [How Finding 2 answers Research Question 2]
- **RQ3:** [How Finding 3 answers Research Question 3]
### Implications
**For [audience 1]:**
- [What this means for them and what action they should consider]
**For [audience 2]:**
- [What this means for them and what action they should consider]
### Comparison with prior work
[How do your findings compare with the studies referenced in the Background section? Do they confirm, contradict, or extend prior work?]
### Limitations
[What caveats should the reader keep in mind? What factors might affect generalizability? Be honest — this is where credibility is built.]
<details>
<summary><strong>💬 Discussion Notes</strong></summary>
- Alternative interpretations of the data
- Edge cases or outliers observed
- Areas where more data would strengthen conclusions
- Potential confounding variables
</details>
---
## 🎯 Conclusions
### Summary
[3–5 sentences. Restate the problem, summarize the key findings, and state the primary recommendation. A reader who skips to this section should understand the entire paper's value.]
### Recommendations
1. **[Recommendation 1]** — [Specific, actionable. What to do, who should do it, expected impact]
2. **[Recommendation 2]** — [Specific, actionable]
3. **[Recommendation 3]** — [Specific, actionable]
### Future work
- [Research direction 1] — [What it would investigate and why it matters]
- [Research direction 2] — [What it would investigate and why it matters]
---
## 🔗 References
_All sources cited in this paper:_
[^1]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^2]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^3]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^4]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^5]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^6]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
[^7]: [Author/Org]. ([Year]). "[Title]." _[Publication]_. <https://example.com>
---
_Last updated: [Date]_

185
scientific-skills/markdown-mermaid-writing/templates/status_report.md Normal file
View File

@@ -0,0 +1,185 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Status Report / Executive Briefing Template
> **Back to [Markdown Style Guide](../markdown_style_guide.md)** — Read the style guide first for formatting, citation, and emoji rules.
**Use this template for:** Weekly/monthly status updates, executive briefings, project health reports, quarterly reviews, sprint retrospectives, or any document that updates stakeholders on progress, risks, and decisions needed. Designed to be read in under 5 minutes by someone with decision-making authority.
**Key features:** TL;DR at the top for executives who won't read further, traffic-light health indicators, explicit "decisions needed" section that surfaces blockers, metrics table with trends, and risk register with mitigations.
**Philosophy:** The #1 failure mode of status reports is burying the important stuff in a wall of accomplishments. Lead with what needs attention. If the reader only has 30 seconds, the TL;DR and health summary give them what they need. If they have 5 minutes, the full report answers every follow-up question they'd ask. Never make leadership dig for the thing they need to act on.
---
## How to Use
1. Copy this file for each reporting period
2. Name it by date: `status-2026-02-14.md` or `status-week-07.md`
3. **Fill in the TL;DR first** — if you can't summarize it, you don't understand it yet
4. Be honest about health status — green means green, not "green because I'm optimistic"
5. Add [Mermaid diagrams](../mermaid_style_guide.md) for progress timelines, architecture changes, or risk impact flows
---
## The Template
Everything below the line is the template. Copy from here:
---
# [Project/Team Name] — Status Report
_[Reporting period: Week of Month DD, YYYY / Month YYYY / Q# YYYY]_
_[Author] · [Date]_
---
## 📋 TL;DR
[3–5 bullet points. One sentence each. The most important things leadership needs to know. If they read nothing else, this is it.]
- **Overall:** [One-sentence project health summary]
- **Progress:** [Key milestone hit or approaching]
- **Blocker:** [The biggest risk or decision needed, or "None" if clear]
- **Next:** [What happens in the next period]
---
## 🚦 Health Summary
| Area | Status | Trend | Notes |
| ------------ | ------------ | ----- | ------------------------- |
| **Schedule** | 🟢 On track | → | [Brief context] |
| **Scope** | 🟡 At risk | ↓ | [What's causing concern] |
| **Budget** | 🟢 On track | → | [Brief context] |
| **Quality** | 🟢 Good | ↑ | [What's improving] |
| **Team** | 🟡 Stretched | → | [Staffing or morale note] |
**Status key:** 🟢 On track · 🟡 At risk · 🔴 Off track / blocked
**Trend key:** ↑ Improving · → Stable · ↓ Declining
---
## ⚠️ Decisions Needed
> **This section is for items that require action from leadership or stakeholders.** If nothing needs a decision, write "No decisions needed this period."
### Decision 1: [Specific question that needs an answer]
**Context:** [Why this decision is needed now — 2–3 sentences]
**Options:**
| Option | Impact | Recommendation |
| ---------- | -------------- | ------------------------------- |
| [Option A] | [What happens] | [Recommended / Not recommended] |
| [Option B] | [What happens] | [Recommended / Not recommended] |
**Deadline:** [When this decision is needed by and what happens if it's delayed]
### Decision 2: [Another question]
[Same structure as above]
---
## 📊 Key Metrics
| Metric | Previous | Current | Target | Trend |
| ---------------------------------- | -------- | ------- | -------- | ------- |
| [Metric 1 — e.g., Sprint velocity] | [Value] | [Value] | [Target] | [↑/→/↓] |
| [Metric 2 — e.g., Open bugs] | [Value] | [Value] | [Target] | [↑/→/↓] |
| [Metric 3 — e.g., Test coverage] | [Value] | [Value] | [Target] | [↑/→/↓] |
| [Metric 4 — e.g., Uptime SLA] | [Value] | [Value] | [Target] | [↑/→/↓] |
<details>
<summary><strong>📊 Detailed Metrics</strong></summary>
[Extended metrics, charts, or breakdowns that support the summary table but would overwhelm the main report.]
</details>
---
## ✅ Accomplishments
### Completed this period
- **[Accomplishment 1]** — [Impact or outcome. Why it matters.]
- **[Accomplishment 2]** — [Impact]
- **[Accomplishment 3]** — [Impact]
### Milestones
| Milestone | Planned date | Actual date | Status |
| ------------- | ------------ | ----------- | -------------- |
| [Milestone 1] | [Date] | [Date or —] | ✅ Complete |
| [Milestone 2] | [Date] | [Date or —] | 🔄 In progress |
| [Milestone 3] | [Date] | — | 📋 Upcoming |
---
## 🔄 In Progress
| Work item | Owner | Started | Expected completion | Status |
| --------- | -------- | ------- | ------------------- | ------------------------------ |
| [Item 1] | [Person] | [Date] | [Date] | [On track / At risk / Blocked] |
| [Item 2] | [Person] | [Date] | [Date] | [Status] |
| [Item 3] | [Person] | [Date] | [Date] | [Status] |
---
## 🚨 Risks and Issues
### Active risks
| Risk | Likelihood | Impact | Mitigation | Owner |
| -------- | ---------- | ------- | --------------------------- | -------- |
| [Risk 1] | 🟡 Medium | 🔴 High | [What we're doing about it] | [Person] |
| [Risk 2] | [Level] | [Level] | [Mitigation] | [Person] |
### Active blockers
| Blocker | Impact | Needed from | Status |
| ----------------------- | ---------------- | ----------------- | -------------------------------- |
| [Blocker 1 — or "None"] | [What's delayed] | [Who can unblock] | [Escalated / Waiting / Resolved] |
<details>
<summary><strong>📋 Resolved Issues</strong></summary>
| Issue | Resolution | Date resolved |
| --------- | --------------------- | ------------- |
| [Issue 1] | [How it was resolved] | [Date] |
| [Issue 2] | [Resolution] | [Date] |
</details>
---
## 📍 Plan for Next Period
### Priorities
1. **[Priority 1]** — [What will be done and expected outcome]
2. **[Priority 2]** — [What will be done]
3. **[Priority 3]** — [What will be done]
### Key dates
| Date | Event |
| ------ | ------------------ |
| [Date] | [What's happening] |
| [Date] | [What's happening] |
---
## 🔗 References
- [Project board / Jira / Linear](https://example.com) — Live work tracking
- [Previous status report](../../docs/project/kanban/sprint-2026-w07-agentic-template-modernization.md) — For context on trends
- [Relevant decision record](../adr/ADR-001-agent-optimized-documentation-system.md) — Background on recent changes
---
_Next report due: [Date]_