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
Files
b376b40f59152b2e55782400a2d7009b107f433d
claude-scientific-skills/docs/project/pr/pr-00000001-markdown-mermaid-skill.md
borealBytes b376b40f59 docs(pr): add PR record for markdown-mermaid writing skill 
Skeleton PR document following the Everything is Code convention.
Contains full changes inventory, impact classification, testing steps,
architecture diagram showing integration with existing skills, and
design decision notes.

Files touched: docs/project/pr/pr-00000001-markdown-mermaid-skill.md
2026-02-19 18:24:45 -05:00

188 lines
10 KiB
Markdown
Raw Blame History

# 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_
Reference in New Issue View Git Blame Copy Permalink