wotann 0.5.0 → 0.5.39

package/skills/scientific/markdown-mermaid-writing/templates/pull_request.md

@@ -0,0 +1,319 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | 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]_

package/skills/scientific/markdown-mermaid-writing/templates/research_paper.md

@@ -0,0 +1,304 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | 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]_