diff --git a/docs/project/pr/pr-00000001-markdown-mermaid-skill.md b/docs/project/pr/pr-00000001-markdown-mermaid-skill.md new file mode 100644 index 0000000..bc75578 --- /dev/null +++ b/docs/project/pr/pr-00000001-markdown-mermaid-skill.md @@ -0,0 +1,187 @@ +# PR-00000001: feat(scientific-communication): add markdown-mermaid-writing skill + +| Field | Value | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| **PR** | `#00000001` | +| **Author** | Clayton Young (Boreal Bytes / Superior Byte Works, LLC) | +| **Date** | 2026-02-19 | +| **Status** | Open โ€” Draft | +| **Branch** | `feat/markdown-mermaid-writing-skill` โ†’ `main` | +| **Related issues** | [#00000001](../issues/issue-00000001-markdown-mermaid-skill.md) | +| **Deploy strategy** | Standard โ€” documentation-only addition, no code execution changes | + +--- + +## ๐Ÿ“‹ Summary + +### What changed and why + +This PR adds a new skill โ€” `markdown-mermaid-writing` โ€” that establishes markdown with embedded Mermaid diagrams as the **default and canonical documentation format** for all scientific skills. The skill ports comprehensive style guides, 24 diagram type references, and 9 document templates from the `borealBytes/opencode` project, and codifies the "source format" philosophy proposed in the K-Dense Discord on 2026-02-19. + +The motivation: scientific outputs currently default to Python-generated or AI-generated images for diagrams. This PR inverts that priority โ€” text-based Mermaid diagrams are the source of truth, downstream image generation is secondary. This gives users version-controlled, token-efficient, universally renderable documentation by default. + +### Impact classification + +| Dimension | Level | Notes | +| ----------------- | ------------------------------------------------------- | ------------------------------------- | +| **Risk** | ๐ŸŸข Low | New skill only โ€” no existing files modified | +| **Scope** | Narrow | One new skill directory | +| **Reversibility** | Easily reversible | Delete the directory to revert | +| **Security** | None | Documentation only | + +--- + +## ๐Ÿ” Changes + +### Change inventory + +| File / Area | Change type | Description | +| --------------------------------------------------- | ----------- | ---------------------------------------------------------------------- | +| `docs/project/issues/issue-00000001-markdown-mermaid-skill.md` | Added | Feature request issue record | +| `docs/project/pr/pr-00000001-markdown-mermaid-skill.md` | Added | This PR record | +| `scientific-skills/markdown-mermaid-writing/SKILL.md` | Added | Main skill documentation with YAML frontmatter and philosophy | +| `scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md` | Added | Full markdown style guide (~730 lines) ported from opencode | +| `scientific-skills/markdown-mermaid-writing/references/mermaid_style_guide.md` | Added | Full mermaid style guide (~454 lines) ported from opencode | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/architecture.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/block.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/c4.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/class.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/complex_examples.md` | Added | Multi-diagram composition patterns | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/er.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/flowchart.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/gantt.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/git_graph.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/kanban.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/mindmap.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/packet.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/pie.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/quadrant.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/radar.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/requirement.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/sankey.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/sequence.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/state.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/timeline.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/treemap.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/user_journey.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/xy_chart.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/references/diagrams/zenuml.md` | Added | Diagram type guide | +| `scientific-skills/markdown-mermaid-writing/templates/decision_record.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/how_to_guide.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/issue.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/kanban.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/presentation.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/project_documentation.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/pull_request.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/research_paper.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/templates/status_report.md` | Added | Document template | +| `scientific-skills/markdown-mermaid-writing/assets/examples/example-research-report.md` | Added | Example demonstrating all diagram types and style rules | + +### Architecture impact + +```mermaid +flowchart TD + accTitle: New Skill Position in Ecosystem + accDescr: Shows markdown-mermaid-writing as the foundation layer that other skills build upon for documentation output + + new["๐Ÿ“„ markdown-mermaid-writing\n(this PR โ€” new skill)"] + writing["โœ๏ธ scientific-writing"] + lit["๐Ÿ“š literature-review"] + schematics["๐ŸŽจ scientific-schematics"] + reports["๐Ÿ“‹ clinical-reports"] + + new -->|"provides style + templates"| writing + new -->|"provides diagram standards"| lit + new -->|"source format before AI polish"| schematics + new -->|"provides document structure"| reports + + classDef newskill fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f + classDef existing fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937 + + class new newskill + class writing,lit,schematics,reports existing +``` + +--- + +## ๐Ÿงช Testing + +### How to verify + +```bash +# Check directory structure +tree scientific-skills/markdown-mermaid-writing/ + +# Check diagram type guide count (expect 24) +ls scientific-skills/markdown-mermaid-writing/references/diagrams/ | wc -l + +# Check template count (expect 9) +ls scientific-skills/markdown-mermaid-writing/templates/ | wc -l + +# Check style guide sizes +wc -l scientific-skills/markdown-mermaid-writing/references/markdown_style_guide.md +wc -l scientific-skills/markdown-mermaid-writing/references/mermaid_style_guide.md + +# Verify SKILL.md has YAML frontmatter +head -10 scientific-skills/markdown-mermaid-writing/SKILL.md +``` + +### Test coverage + +| Test type | Status | Notes | +| ----------------- | ----------- | ---------------------------------- | +| Unit tests | โฌœ N/A | Documentation skill โ€” no code | +| Manual testing | โœ… Verified | Directory structure and file content reviewed | +| Format validation | โœ… Verified | Markdown style guide rules applied to all docs | + +### Edge cases considered + +- Attribution headers added to all ported files โ€” license compliance +- All Mermaid diagrams in new documents use `classDef`, not `%%{init}` โ€” dark/light mode compatible +- `accTitle` + `accDescr` on every diagram in new documents โ€” accessibility + +--- + +## ๐Ÿ”’ Security + +### Security checklist + +- [x] No secrets, credentials, API keys, or PII in the diff +- [x] Authentication/authorization changes reviewed โ€” N/A +- [x] Input validation reviewed โ€” N/A (documentation only) +- [x] License and attribution retained โ€” Apache-2.0, source credited + +--- + +## ๐Ÿš€ Deployment + +No deployment steps needed โ€” documentation-only skill addition. + +### Rollback + +```bash +git revert HEAD~[n] # or simply delete the skill directory +rm -rf scientific-skills/markdown-mermaid-writing/ +``` + +--- + +## ๐Ÿ“ Design decisions + +- **"Source format" over generated images** โ€” Mermaid diagrams are text, diffable, versionable, and renderable by any markdown viewer without a build step. AI/Python images are downstream artifacts. This PR establishes that hierarchy explicitly. +- **Full port of opencode style guides** โ€” Rather than a summary, the complete guides are included so agents using this skill have the full context without additional lookups. The token cost of loading this skill is offset by eliminating per-document style lookups. +- **Apache-2.0 attribution preserved** โ€” All ported content retains the original license header. MIT (claude-scientific-skills) is compatible with Apache-2.0 for downstream use. + +No ADR created โ€” this is a documentation addition with no architectural tradeoff. + +--- + +## ๐Ÿ”— References + +- [Issue #00000001](../issues/issue-00000001-markdown-mermaid-skill.md) โ€” Feature request +- [opencode repository](https://github.com/borealBytes/opencode) โ€” Source of ported style guides (Apache-2.0) +- [K-Dense Discord thread](https://discord.com/channels/k-dense) โ€” Originating conversation, 2026-02-19 + +--- + +_Last updated: 2026-02-19_