diff --git a/business-growth/.claude-plugin/plugin.json b/business-growth/.claude-plugin/plugin.json index 6945ceb6..e268459b 100644 --- a/business-growth/.claude-plugin/plugin.json +++ b/business-growth/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "business-growth-skills", - "description": "5 business & growth skills: customer success manager, sales engineer, revenue operations, contract & proposal writer, and BizDev-toolkit. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "4 business & growth skills plus a router: customer success manager (health scoring, churn), sales engineer (RFP analysis, PoC planning), revenue operations (pipeline, forecast accuracy, GTM), and contract & proposal writer. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -12,4 +12,4 @@ "skills": [ "./skills" ] -} +} \ No newline at end of file diff --git a/business-growth/skills/business-growth-skills/SKILL.md b/business-growth/skills/business-growth-skills/SKILL.md index 74bcd642..4c5fb183 100644 --- a/business-growth/skills/business-growth-skills/SKILL.md +++ b/business-growth/skills/business-growth-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "business-growth-skills" -description: "4 business growth agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Customer success (health scoring, churn), sales engineer (RFP), revenue operations (pipeline, GTM), contract & proposal writer. Python tools (stdlib-only)." +description: "Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -16,41 +16,30 @@ agents: - openclaw --- -# Business & Growth Skills +# Business & Growth Skills — Router -4 production-ready skills for customer success, sales, and revenue operations. +This plugin bundles **4 skills** (this router is the 5th folder under `business-growth/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read business-growth/skills/customer-success-manager/SKILL.md -``` +Match the request, then load `business-growth/skills//SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/business-growth -``` +| Request signals | Skill | Path | +|---|---|---| +| Customer health scores, churn risk, expansion plays | customer-success-manager | `skills/customer-success-manager/` | +| RFP/RFI coverage, competitive positioning, PoC plans | sales-engineer | `skills/sales-engineer/` | +| Pipeline coverage, forecast accuracy (MAPE), GTM efficiency | revenue-operations | `skills/revenue-operations/` | +| Proposals, contracts, statements of work, DPAs | contract-and-proposal-writer | `skills/contract-and-proposal-writer/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Customer Success Manager | `customer-success-manager/` | Health scoring, churn prediction, expansion | -| Sales Engineer | `sales-engineer/` | RFP analysis, competitive matrices, PoC planning | -| Revenue Operations | `revenue-operations/` | Pipeline analysis, forecast accuracy, GTM metrics | -| Contract & Proposal Writer | `contract-and-proposal-writer/` | Proposal generation, contract templates | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash +# Example: route an account-health request +cat business-growth/skills/customer-success-manager/SKILL.md python3 business-growth/skills/customer-success-manager/scripts/health_score_calculator.py --help -python3 business-growth/skills/revenue-operations/scripts/pipeline_analyzer.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and metrics, not manual estimates +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Use the skills' Python scorers for metrics, not manual estimates; deal/contract outputs are drafts for human legal/commercial review. diff --git a/business-operations/skills/capacity-planner/SKILL.md b/business-operations/skills/capacity-planner/SKILL.md index 59ff19ed..a6ba39ee 100644 --- a/business-operations/skills/capacity-planner/SKILL.md +++ b/business-operations/skills/capacity-planner/SKILL.md @@ -83,6 +83,13 @@ It produces three artifacts: All three accept `--input ` (JSON), `--output {markdown,json}`, `--sample` (built-in example), and `--help`. Stdlib only. +## Quick example + +```bash +# Emits an Erlang-C capacity model (required headcount + P50/P90/P99 breach probabilities) for the built-in example +cd business-operations/skills/capacity-planner && python3 scripts/capacity_modeler.py --sample +``` + ## References - `references/queueing_theory_canon.md` — Erlang, Little, Hopp & diff --git a/business-operations/skills/internal-comms/SKILL.md b/business-operations/skills/internal-comms/SKILL.md index 312fba79..49cdb79a 100644 --- a/business-operations/skills/internal-comms/SKILL.md +++ b/business-operations/skills/internal-comms/SKILL.md @@ -1,6 +1,6 @@ --- name: internal-comms -description: Use when a Head of People Ops, BizOps lead, or Internal Communications owner needs to draft and sequence an internal-only change-management communication — a re-org announcement, a tool rollout, a policy change, a benefit change, a leadership transition, a layoff, an acquisition close, or an internal product launch — and the audience is employees (not customers). Triggers on "all-hands announcement", "town-hall script", "change comms", "internal newsletter", "rollout comms", "policy change announcement", "re-org announcement", "internal FAQ", "manager talking points", "Prosci ADKAR", "Kotter 8-step", "layoff comms", "RIF comms", "internal memo". Pairs Prosci ADKAR (Awareness / Desire / Knowledge / Ability / Reinforcement) and Kotter's 8-step change model with deterministic stdlib-only Python tools to produce a sequenced touchpoint calendar, a Kotter-compliant primary announcement, an audience-segmented FAQ, and manager cascade talking points. Industry-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Distinct from marketing-skill/* (external/customer-facing), c-level-advisor/internal-narrative (strategic framing, not tactical drafts), and c-level-advisor/change-management (executive change strategy, not the comms package itself). +description: Use when a Head of People Ops, BizOps lead, or Internal Communications owner needs to draft and sequence an internal-only change-management communication — a re-org announcement, a tool rollout, a policy change, a leadership transition, a layoff, an acquisition close, or an internal product launch — and the audience is employees (not customers). Pairs Prosci ADKAR and Kotter's 8-step change model with deterministic stdlib-only Python tools to produce a sequenced touchpoint calendar, a Kotter-compliant primary announcement, an audience-segmented FAQ, and manager cascade talking points; industry-tuned via --profile {tech-startup, scaleup, enterprise, public-company, non-profit}. Triggers on "all-hands announcement", "change comms", "rollout comms", "re-org announcement", "manager talking points", "layoff comms". version: 2.8.0 author: claude-code-skills license: MIT @@ -59,6 +59,13 @@ Five-step deterministic flow. Follow in order. All three: stdlib only, `--help` and `--sample` exit 0, accept `--input ` and `--output {markdown,json}`. +## Quick example + +```bash +# Emits the 4-artifact comms package (pre-comm, announcement, FAQ, follow-up) for the built-in tool-rollout example +cd business-operations/skills/internal-comms && python3 scripts/comms_template_filler.py --sample +``` + ## References - `references/change_management_canon.md` — Jeff Hiatt *ADKAR* (Prosci), John Kotter *Leading Change* (8-step), William Bridges *Managing Transitions* (Endings / Neutral Zone / Beginnings), Edgar Schein *Organizational Culture and Leadership*, McKinsey 7-S framework, Heath brothers *Switch*, Patrick Lencioni *The Advantage*. diff --git a/business-operations/skills/knowledge-ops/SKILL.md b/business-operations/skills/knowledge-ops/SKILL.md index 334484ba..06902b76 100644 --- a/business-operations/skills/knowledge-ops/SKILL.md +++ b/business-operations/skills/knowledge-ops/SKILL.md @@ -1,6 +1,6 @@ --- name: knowledge-ops -description: Use when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding, expense reimbursement, system-access provisioning, customer-escalation playbook) — including 5W2H completeness checks (Who-What-When-Where-Why-How-HowMuch), cross-link and orphan-page validation across a sprawling Notion/Confluence/Obsidian wiki, KB ingestion + hygiene reporting, ops onboarding doc generation, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Kaoru Ishikawa's 5W2H method, Atul Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4 Service Operation, FDA 21 CFR Part 211, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists. Distinct from `engineering/llm-wiki` (Karpathy-style personal PKM second brain), `engineering-team/runbook-generator` (system-ops production debugging runbook), `project-management/*` (Jira/Confluence delivery + ticket tracking), and sibling `business-operations/process-mapper` (BPMN process *design*, while knowledge-ops is process *documentation*). +description: Use when a Head of Ops, Knowledge Manager, or TPM-Internal needs to author, validate, or clean up company SOPs and internal runbooks (procurement intake, vendor offboarding, incident-comms cascade, employee onboarding) — including 5W2H completeness checks (Who-What-When-Where-Why-How-HowMuch), cross-link and orphan-page validation across a sprawling Notion/Confluence/Obsidian wiki, KB ingestion + hygiene reporting, and runbook step verification (named owner, expected duration, observable success signal, rollback path, escalation contact). Pairs Ishikawa's 5W2H method, Gawande's *The Checklist Manifesto*, ISO 9001, ITIL v4, and Google SRE Workbook runbook discipline with deterministic stdlib-only Python tools that score completeness, detect anti-patterns, and emit prioritized cleanup lists (e.g., "validate this runbook before it goes into rotation", "audit our Confluence wiki for stale and orphaned SOPs"). context: fork version: 2.8.0 author: claude-code-skills @@ -18,7 +18,7 @@ Company SOP + internal runbook authoring, 5W2H completeness validation, and KB h An ops organization three years in accumulates a sprawl: 600 Notion pages, 200 Confluence runbooks, three Obsidian vaults, a `Drive/SOPs/` folder, and a `Slack #ops-questions` channel that exists because nobody can find the canonical doc. Predictable failure modes: 1. **No owner** — 40% of SOPs name "the team" instead of a person. When the doc rots, nobody is accountable. -2. **No last-reviewed date** — a 2023 vendor-offboarding SOP still references a procurement tool sunset in 2024. +2. **No last-reviewed date** — a years-old vendor-offboarding SOP still references a procurement tool that was sunset over a year ago. 3. **Vague success signals** — runbook step 4 says "verify the service is up". A new operator can't tell what that means. 4. **No rollback path** — incident-comms cascade runbook tells you how to send the alert. It doesn't tell you how to retract it when the alert was wrong. 5. **Orphan pages** — half the KB has no inbound links. Nobody finds them via navigation; they only exist because somebody knew the URL. @@ -52,6 +52,13 @@ Four-step deterministic flow (matches the ops org's actual workflow, not an abst **`scripts/kb_ingester.py`** — Walks a directory of markdown files (Notion export, Confluence space export, Obsidian vault, `Drive/SOPs/` directory). Extracts: (a) cross-link map (which page references which, via markdown `[link](path)` syntax), (b) glossary candidates (frequently used proper nouns and acronyms that recur in 3+ docs without a single canonical definition page), (c) orphan pages (no inbound links from anywhere in the vault), (d) glossary drift (the same term defined or used inconsistently across docs — e.g., "CSM" expanded differently in two places), (e) stale pages (no edit in > 12 months, detected via filesystem mtime or YAML `last_reviewed` frontmatter), (f) missing-owner pages (no `owner:` field in frontmatter). Emits a KB health report markdown with a prioritized top-20 cleanup list ranked by `staleness × inbound-link-count` (high-traffic stale docs first). `--sample` builds a tiny synthetic 8-page vault in a tmpdir and runs the full pipeline against it. Stdlib only. +## Quick example + +```bash +# Builds a synthetic 8-page vault and emits a KB health report (orphans, stale pages, glossary drift, top-20 cleanup list) +cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample +``` + ## References - `references/5w2h_sop_canon.md` — Kaoru Ishikawa's 5W2H method, Toyota standard-work discipline, Atul Gawande's checklist manifesto, Atlassian Confluence SOP guidance, ISO 9001 SOP requirements, ITIL v4 Service Operation, FDA 21 CFR Part 211. Eight cited sources covering SOP authoring canon. diff --git a/business-operations/skills/process-mapper/SKILL.md b/business-operations/skills/process-mapper/SKILL.md index d15c9aaf..0043d906 100644 --- a/business-operations/skills/process-mapper/SKILL.md +++ b/business-operations/skills/process-mapper/SKILL.md @@ -47,6 +47,13 @@ Five-step deterministic flow: **`scripts/cycle_time_analyzer.py`** — Computes total P50 and P90 cycle time, value-add ratio (VA%), wait %, rework %, and a Little's-Law throughput estimate (WIP / cycle time). Per Lean canon: VA% > 25% = HEALTHY, 10–25% = TYPICAL (most non-manufacturing processes land here), < 10% = WASTE-HEAVY. +## Quick example + +```bash +# Renders a BPMN-style swim-lane diagram + normalized JSON for the built-in 6-stage procurement-intake example +cd business-operations/skills/process-mapper && python3 scripts/process_documenter.py --sample +``` + ## References - `references/lean_six_sigma_canon.md` — TIMWOOD wastes, value-stream mapping, Theory of Constraints, Kanban WIP, Little's Law. Cites Womack & Jones, Rother & Shook, Goldratt, Ohno, Liker, Pyzdek, Anderson. diff --git a/business-operations/skills/procurement-optimizer/SKILL.md b/business-operations/skills/procurement-optimizer/SKILL.md index 6c9d05c7..e0e02526 100644 --- a/business-operations/skills/procurement-optimizer/SKILL.md +++ b/business-operations/skills/procurement-optimizer/SKILL.md @@ -1,6 +1,6 @@ --- name: procurement-optimizer -description: Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs to do a spend audit, spend categorization (UNSPSC-aligned), purchasing-cycle analysis, or risk-balanced supplier consolidation. Triggers on "spend audit", "SaaS audit", "spend categorization", "supplier rationalization", "supplier consolidation", "purchasing cycle", "procurement review", "category strategy", "duplicate SaaS", "renewal cluster". Ships 3 stdlib-only Python tools (UNSPSC-aligned spend categorizer with Pareto breakdown and industry profiles, purchasing-cycle analyzer that surfaces bottleneck categories per Goldratt's Theory of Constraints, supplier-consolidation planner that refuses single-source recommendations for tier-1 categories without a documented break-glass plan), 3 reference docs each citing 7+ authoritative sources (A.T. Kearney / Hackett / Spend Matters / UNSPSC / Productiv / Vendr / Tropic / IACCM / ISM / BCG), and a 20-minute spend-intake template. Distinct from sibling vendor-management (performance scoring of vendors you keep paying), finance/financial-analysis (close + report, not category strategy), and c-level-advisor/general-counsel-advisor (contract law, not category rationalization). +description: Use when running an annual SaaS audit, doing category-level spend review, or rationalizing the supplier base — when the user needs a spend audit, spend categorization (UNSPSC-aligned with Pareto breakdown and industry profiles), purchasing-cycle analysis (bottleneck categories per Goldratt's Theory of Constraints), or risk-balanced supplier consolidation that refuses single-source recommendations for tier-1 categories without a documented break-glass plan. Triggers on "spend audit", "SaaS audit", "spend categorization", "supplier rationalization", "supplier consolidation", "category strategy", "duplicate SaaS", "renewal cluster". version: 2.8.0 author: claude-code-skills license: MIT @@ -99,6 +99,13 @@ Combine the 3 artifacts into a BizOps-ready digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific category priorities accept `--profile {tech-startup,scaleup,enterprise,services,manufacturing}`. +## Quick example + +```bash +# Emits a UNSPSC-aligned spend categorization with Pareto breakdown for the built-in sample spend file +cd business-operations/skills/procurement-optimizer && python3 scripts/spend_categorizer.py --sample +``` + ## References - `references/spend_management_canon.md` — A.T. Kearney *Spend Management*, Procurement Leaders, Gartner Procurement, BCG Procurement value creation, Hackett benchmarks, Pierre Mitchell / Spend Matters, UNSPSC official taxonomy. diff --git a/business-operations/skills/vendor-management/SKILL.md b/business-operations/skills/vendor-management/SKILL.md index 8eec66e4..490714c8 100644 --- a/business-operations/skills/vendor-management/SKILL.md +++ b/business-operations/skills/vendor-management/SKILL.md @@ -1,6 +1,6 @@ --- name: vendor-management -description: Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard, tracking SLA compliance, classifying third-party risk, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Triggers on "vendor SLA", "vendor scorecard", "third-party risk", "TPRM", "vendor review", "SaaS audit", "supplier performance", "vendor health check", "renewal review". Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Ships 3 stdlib-only Python tools (vendor scorer with industry tuning, SLA compliance tracker with credit-claim flags, vendor risk classifier across 4 risk vectors), 3 reference docs each citing 7+ authoritative sources (Gartner / Shared Assessments / NIST / ISO 27036 / breach post-mortems), and a 5-vendor catalog template. Distinct from c-level-advisor/general-counsel-advisor (contract law, not operational management), business-growth/contract-and-proposal-writer (outbound proposals, not inbound vendor scoring), and sibling procurement-optimizer (spend categorization, not vendor performance). +description: Use when reviewing, scoring, or auditing third-party SaaS / vendor relationships — running a vendor scorecard with industry tuning, tracking SLA compliance with credit-claim flags, classifying third-party risk across 4 risk vectors, preparing a tier-1 vendor review, or auditing the SaaS portfolio. Forks context so large vendor catalogs (50-500 line items) and SLA logs don't pollute the parent thread. Triggers on "vendor SLA", "vendor scorecard", "third-party risk", "TPRM", "vendor review", "supplier performance", "vendor health check", "renewal review". context: fork version: 2.8.0 author: claude-code-skills @@ -110,6 +110,13 @@ Combine the 3 artifacts into a final BizOps / VMO digest: All three accept `--input` (JSON), `--output` (markdown path), `--sample` (run with built-in sample data), and `--help`. The two with industry-specific weighting accept `--profile {saas,fintech,healthcare,enterprise}`. +## Quick example + +```bash +# Emits a weighted vendor scorecard (industry-tuned dimensions + per-vendor verdict) for the built-in sample catalog +cd business-operations/skills/vendor-management && python3 scripts/vendor_scorer.py --sample +``` + ## References - `references/vendor_management_canon.md` — Gartner / Shared Assessments / ISO 27036 / NIST 800-161 / Forrester / ISACA / Vendr industry reports diff --git a/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md b/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md index d2fec095..d969594d 100644 --- a/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/boardroom/SKILL.md @@ -1,6 +1,6 @@ --- name: "boardroom" -description: "/cs:boardroom — 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo." +description: "/cs:boardroom — 6-phase multi-role deliberation across the C-suite with Phase 2 isolation, critic pre-screen, and synthesis. Outputs a board memo. Use when a decision spans multiple executive domains — e.g. a pricing change touching finance, positioning, and product, or a raise-vs-cut runway call." --- # /cs:boardroom — Multi-Role Boardroom Deliberation diff --git a/c-level-advisor/c-level-agents/skills/brief/SKILL.md b/c-level-advisor/c-level-agents/skills/brief/SKILL.md index 61f98d50..aa5f7a8a 100644 --- a/c-level-advisor/c-level-agents/skills/brief/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/brief/SKILL.md @@ -1,6 +1,6 @@ --- name: "brief" -description: "/cs:brief — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline." +description: "/cs:brief — Generate a one-page strategy brief from an office-hours intake. First step in the strategic sprint pipeline. Use when a strategic question needs to be framed before boardroom deliberation — e.g. locking options, assumptions, and success criteria for a pricing change or a market-entry decision." --- # /cs:brief — One-Page Strategy Brief @@ -68,6 +68,11 @@ A single Markdown file under `~/.claude/briefs/YYYY-MM-DD-.md` with this s - [ ] cs-coo-advisor - [ ] cs-chro-advisor - [ ] cs-ciso-advisor +- [ ] cs-general-counsel-advisor +- [ ] cs-cdo-advisor +- [ ] cs-caio-advisor +- [ ] cs-cco-advisor +- [ ] cs-vpe-advisor - [ ] cs-chief-of-staff ## Success Criteria diff --git a/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md b/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md index 3934054e..ca59e815 100644 --- a/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/c-level-agents/SKILL.md @@ -1,6 +1,6 @@ --- name: "c-level-agents" -description: "Founder-mode executive team. 8 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, Chief of Staff) and 17 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." +description: "Founder-mode executive team. 13 cs-* C-suite agents (CFO, CMO, CRO, CPO, COO, CHRO, CISO, GC, CDO, CAIO, CCO, VPE, Chief of Staff) and 21 /cs:* slash commands for forcing-question office hours, multi-role boardroom deliberation, strategic sprint pipeline, and meta routing. Use when the founder needs a virtual executive team, when invoking /cs:* commands, or when orchestrating multi-role decisions." license: MIT metadata: version: 1.0.0 @@ -8,8 +8,8 @@ metadata: category: c-level domain: executive-orchestration updated: 2026-05-12 - agents: cs-cfo-advisor, cs-cmo-advisor, cs-cro-advisor, cs-cpo-advisor, cs-coo-advisor, cs-chro-advisor, cs-ciso-advisor, cs-chief-of-staff - commands: cs-office-hours, cs-cfo-review, cs-cmo-review, cs-cpo-review, cs-cro-review, cs-cto-review, cs-ciso-review, cs-gc-review, cs-brief, cs-boardroom, cs-decide, cs-execute, cs-post-mortem, cs-founder-mode, cs-onboard, cs-cross-eval, cs-freeze + agents: cs-cfo-advisor, cs-cmo-advisor, cs-cro-advisor, cs-cpo-advisor, cs-coo-advisor, cs-chro-advisor, cs-ciso-advisor, cs-general-counsel-advisor, cs-cdo-advisor, cs-caio-advisor, cs-cco-advisor, cs-vpe-advisor, cs-chief-of-staff + commands: cs-office-hours, cs-cfo-review, cs-cmo-review, cs-cpo-review, cs-cro-review, cs-cto-review, cs-ciso-review, cs-gc-review, cs-cdo-review, cs-caio-review, cs-cco-review, cs-vpe-review, cs-brief, cs-boardroom, cs-decide, cs-execute, cs-post-mortem, cs-founder-mode, cs-onboard, cs-cross-eval, cs-freeze --- # c-level-agents — Founder-Mode Executive Team @@ -22,7 +22,7 @@ founder mode, virtual c-suite, executive team, boardroom, office hours, cfo revi ## What This Plugin Provides -### 8 cs-* Agents (in `agents/`) +### 13 cs-* Agents (in `agents/`) Each agent wraps an existing c-level skill and adds: - A distinct cognitive voice (numerate skeptic, narrative-first, etc.) @@ -32,9 +32,9 @@ Each agent wraps an existing c-level skill and adds: See `../../references/persona-voices.md` for voice specs. -### 17 /cs:* Slash Commands (in `skills/`) +### 21 /cs:* Slash Commands (in `skills/`) -**Forcing-question office hours (8):** +**Forcing-question office hours (12):** - `/cs:office-hours` — YC-style 6-question intake - `/cs:cfo-review` — unit economics, runway, dilution - `/cs:cmo-review` — ICP, CAC payback, positioning @@ -43,6 +43,10 @@ See `../../references/persona-voices.md` for voice specs. - `/cs:cto-review` — architecture risk, scaling cliff - `/cs:ciso-review` — threat model, blast radius, compliance - `/cs:gc-review` — contracts, IP, regulatory, term sheets +- `/cs:cdo-review` — training-data rights, data products, data assets +- `/cs:caio-review` — model selection, evals, AI risk, AI costs +- `/cs:cco-review` — GRR/NRR decomposition, churn root cause, CS coverage +- `/cs:vpe-review` — DORA metrics, cycle time, eng hiring funnel, team structure **Strategic sprint pipeline (5):** - `/cs:brief` → `/cs:boardroom` → `/cs:decide` → `/cs:execute` → `/cs:post-mortem` @@ -86,7 +90,7 @@ User question ## Integration Points -- **Existing 28 c-level skills** — wrapped, not replaced +- **Existing 33 c-level skills** — wrapped, not replaced - **decision-logger** — every `/cs:decide` writes here - **chief-of-staff** — routing layer the agent orchestrates - **board-meeting** — protocol the `/cs:boardroom` command runs diff --git a/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md b/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md index ae62b020..dd135a23 100644 --- a/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/caio-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "caio-review" -description: "/cs:caio-review — Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring." +description: "/cs:caio-review — Eval-demanding Chief AI Officer interrogation of any plan that involves AI: model selection, risk classification, cost economics, or AI hiring. Use when shipping an AI feature without an eval set, choosing between API, fine-tune, and self-hosted, or classifying a use case under the EU AI Act." --- # /cs:caio-review — CAIO Forcing Questions @@ -125,7 +125,7 @@ python ../../../skills/chief-ai-officer-advisor/scripts/ai_cost_economics.py wor - `/cs:gc-review` — for AI vendor contracts, output liability, training-data licensing - `/cs:ciso-review` — for prompt injection / jailbreak / training-data poisoning threat model - `/cs:cfo-review` — for multi-year vendor or GPU commitment TCO -- `/cs:chro-review` — for AI team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for AI team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 60` — on multi-year AI commitments diff --git a/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md index b3af502f..9de92d43 100644 --- a/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cco-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cco-review" -description: "/cs:cco-review — Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring." +description: "/cs:cco-review — Retention-obsessed Chief Customer Officer interrogation of any plan that touches customer retention, segmentation, CS team sizing, or CS team hiring. Use when gross retention is slipping, before approving CSM headcount, or when deciding which customer segments to keep or fire." --- # /cs:cco-review — CCO Forcing Questions @@ -115,7 +115,7 @@ python ../../../skills/chief-customer-officer-advisor/scripts/cs_coverage_calcul - `/cs:cpo-review` — if churn root cause is product_fit or no_value_realized - `/cs:cro-review` — if expansion math or comp alignment is in question - `/cs:cfo-review` — for CS cost commitments and retention-impact-on-revenue -- `/cs:chro-review` — for CS hires, comp, ladder +- `cs-chro-advisor` agent — for CS hires, comp, ladder - `/cs:decide` — log the verdict - `/cs:freeze 30` — on multi-year CS comp plan changes diff --git a/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md index f5d3aaba..b962d71d 100644 --- a/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cdo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cdo-review" -description: "/cs:cdo-review — Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring." +description: "/cs:cdo-review — Decision-driven Chief Data Officer interrogation of any plan that touches training data, data architecture, data productization, or data team hiring. Use when validating training-data rights before model work, choosing warehouse vs lakehouse vs mesh, or valuing data assets for productization or M&A." --- # /cs:cdo-review — CDO Forcing Questions @@ -111,7 +111,7 @@ python ../../../skills/chief-data-officer-advisor/scripts/data_asset_valuator.py - `/cs:gc-review` — for any productization or licensing path - `/cs:ciso-review` — for any architecture change touching customer data - `/cs:cfo-review` — for build-vs-buy TCO and M&A valuation math -- `/cs:chro-review` — for data team hires (comp, ladder, leveling) +- `cs-chro-advisor` agent — for data team hires (comp, ladder, leveling) - `/cs:decide` — log the verdict - `/cs:freeze 90` — on multi-year infrastructure contracts diff --git a/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md index 526fa37f..bc59bd04 100644 --- a/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cfo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cfo-review" -description: "/cs:cfo-review — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation." +description: "/cs:cfo-review — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when a plan commits meaningful spend — e.g. a hiring wave, a fundraise decision, or a new channel budget." --- # /cs:cfo-review — CFO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md b/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md index 607040c8..db874772 100644 --- a/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/ciso-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "ciso-review" -description: "/cs:ciso-review — Risk-paranoid interrogation of any plan that touches data, compliance, or production access." +description: "/cs:ciso-review — Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features that handle customer data, before a SOC 2 / ISO audit, or after any incident or near-miss." --- # /cs:ciso-review — CISO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md index f0c13f65..755ae792 100644 --- a/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cmo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cmo-review" -description: "/cs:cmo-review — Narrative-first interrogation of positioning, ICP, message house, and channel mix." +description: "/cs:cmo-review — Narrative-first interrogation of positioning, ICP, message house, and channel mix. Use when launching a campaign or repositioning, or when CAC is rising and the one-sentence positioning test fails." --- # /cs:cmo-review — CMO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md index ec66bed5..1e32640f 100644 --- a/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cpo-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cpo-review" -description: "/cs:cpo-review — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus." +description: "/cs:cpo-review — JTBD-driven interrogation of product roadmap, PMF signal, and portfolio focus. Use when committing a quarter's roadmap, deciding whether to kill a feature, or claiming PMF without a retention curve." --- # /cs:cpo-review — CPO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md index 169d32ca..b3f068d2 100644 --- a/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cro-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cro-review" -description: "/cs:cro-review — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time." +description: "/cs:cro-review — Pipeline-paranoid interrogation of revenue, win rate, NRR, and ramp time. Use when the forecast misses pipeline coverage, win rates drop, or before scaling the sales team." --- # /cs:cro-review — CRO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md b/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md index 578a2781..5b7936fa 100644 --- a/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cross-eval/SKILL.md @@ -1,6 +1,6 @@ --- name: "cross-eval" -description: "/cs:cross-eval — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation." +description: "/cs:cross-eval — Multi-model consensus on a board memo or strategy brief. Claude + Codex + Gemini cross-review with graceful degradation. Use when a high-stakes memo needs an independent sanity check before the boardroom — e.g. a bet-the-company pivot or fundraise terms." --- # /cs:cross-eval — Multi-Model Consensus diff --git a/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md b/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md index 26850b60..e28ee69a 100644 --- a/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/cto-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "cto-review" -description: "/cs:cto-review — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy." +description: "/cs:cto-review — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an architecture, planning for 10x load, or weighing a rebuild against a vendor." --- # /cs:cto-review — CTO Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/decide/SKILL.md b/c-level-advisor/c-level-agents/skills/decide/SKILL.md index e081111d..43d5b54b 100644 --- a/c-level-advisor/c-level-agents/skills/decide/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/decide/SKILL.md @@ -1,6 +1,6 @@ --- name: "decide" -description: "/cs:decide — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference." +description: "/cs:decide — Log a decision to two-layer memory via decision-logger. Approved memo becomes durable; raw transcripts kept for reference. Use when the founder has approved a boardroom memo and the decision must become durable company memory — e.g. right after /cs:boardroom concludes." --- # /cs:decide — Log the Decision diff --git a/c-level-advisor/c-level-agents/skills/execute/SKILL.md b/c-level-advisor/c-level-agents/skills/execute/SKILL.md index e3897d4b..dce7266d 100644 --- a/c-level-advisor/c-level-agents/skills/execute/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/execute/SKILL.md @@ -1,6 +1,6 @@ --- name: "execute" -description: "/cs:execute — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision." +description: "/cs:execute — Generate a 90-day execution plan with weekly milestones, DRIs, and check-in cadence from an approved decision. Use when a logged decision needs to become an operating plan — e.g. turning an approved market-entry call into weekly milestones with DRIs." --- # /cs:execute — 90-Day Execution Plan diff --git a/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md b/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md index 2f3203a6..89fbba96 100644 --- a/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/founder-mode/SKILL.md @@ -1,6 +1,6 @@ --- name: "founder-mode" -description: "/cs:founder-mode — Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point." +description: "/cs:founder-mode — Auto-routes any founder question to the right C-role advisor or to /cs:boardroom for multi-role topics. The single-command entry point. Use when a founder asks any strategic question without knowing which advisor or command fits — e.g. 'runway pressure' routes to the CFO, 'gross retention dropped' routes to the CCO." --- # /cs:founder-mode — The Auto-Router @@ -18,14 +18,18 @@ The router (via `cs-chief-of-staff`) does keyword + intent matching: | Signal in question | Route | |---|---| | burn, runway, fundraise, dilution, model, LTV, CAC | `cs-cfo-advisor` | -| pipeline, win rate, forecast, NRR, churn, ramp | `cs-cro-advisor` | +| pipeline, win rate, forecast, quota, ramp, sales motion | `cs-cro-advisor` | | positioning, ICP, message, brand, channel, campaign | `cs-cmo-advisor` | | roadmap, PMF, JTBD, North Star, RICE, kill | `cs-cpo-advisor` | | cadence, OKR, scorecard, DRI, operating system, rhythm | `cs-coo-advisor` | | hiring, comp, ladder, level, attrition, eNPS, equity | `cs-chro-advisor` | | security, threat, breach, compliance, audit, SOC 2 | `cs-ciso-advisor` | | architecture, scaling, tech debt, SLO, latency | `cs-cto-advisor` | -| contract, IP, term sheet, regulator, license | `/cs:gc-review` | +| contract, IP, term sheet, regulator, license | `cs-general-counsel-advisor` | +| retention, GRR, NRR, churn, customer success, CSM, time-to-value, renewals | `cs-cco-advisor` | +| training data, data rights, consent, data asset, warehouse, lakehouse, data mesh | `cs-cdo-advisor` | +| model selection, eval, hallucination, AI risk, EU AI Act, fine-tune, build vs buy AI | `cs-caio-advisor` | +| DORA, cycle time, deploy frequency, eng hiring funnel, team topology, delivery throughput | `cs-vpe-advisor` | | strategy, vision, board, M&A, raise, exit | `cs-ceo-advisor` | | **2+ signals from different roles** | `/cs:boardroom` | | **ambiguous** | `/cs:office-hours` first, then route | @@ -83,6 +87,9 @@ gstack requires the founder to know all 23 slash commands and pick the right one /cs:founder-mode "the win rate dropped 20% this month" → cs-cro-advisor +/cs:founder-mode "gross retention dropped 5 points this quarter" + → cs-cco-advisor + /cs:founder-mode "let's hire a VP Marketing" → boardroom (CHRO + CMO + CFO touched) diff --git a/c-level-advisor/c-level-agents/skills/freeze/SKILL.md b/c-level-advisor/c-level-agents/skills/freeze/SKILL.md index 72d85901..9b14684e 100644 --- a/c-level-advisor/c-level-agents/skills/freeze/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/freeze/SKILL.md @@ -1,6 +1,6 @@ --- name: "freeze" -description: "/cs:freeze — Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer." +description: "/cs:freeze — Lock a strategic decision for a cooldown period to prevent impulse reversal. Mirrors gstack's safety primitives for the business layer. Use when an irreversible decision was made under pressure — e.g. a layoff plan or multi-year contract — and deserves a cooling-off lock before execution." --- # /cs:freeze — Cooldown Lock on a Decision diff --git a/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md b/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md index a6f3a2ab..dc9b7c73 100644 --- a/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/gc-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "gc-review" -description: "/cs:gc-review — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface." +description: "/cs:gc-review — General Counsel interrogation of contracts, IP, regulatory, term sheets, and employment-law surface. Use when reviewing a term sheet before signing, redlining a customer MSA, or checking IP assignment and regulatory exposure on a new product." --- # /cs:gc-review — General Counsel Forcing Questions diff --git a/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md b/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md index 504e698f..727feebe 100644 --- a/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/office-hours/SKILL.md @@ -1,6 +1,6 @@ --- name: "office-hours" -description: "/cs:office-hours — YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit." +description: "/cs:office-hours — YC-style 6-question founder interrogation before any advice. Forces clarity on problem, customer, distribution, defensibility, capital, and founder fit. Use when a founder question is too vague to route — e.g. 'should we grow faster?' — or before drafting a strategy brief." --- # /cs:office-hours — Six-Question Founder Interrogation diff --git a/c-level-advisor/c-level-agents/skills/onboard/SKILL.md b/c-level-advisor/c-level-agents/skills/onboard/SKILL.md index 2230e23e..47cbdef2 100644 --- a/c-level-advisor/c-level-agents/skills/onboard/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: "onboard" -description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md. The first command to run when starting with c-level-agents." +description: "/cs:onboard — Founder interview that populates ~/.claude/company-context.md using the canonical 7-dimension cs-onboard schema. The first command to run when starting with c-level-agents. Use when setting up the virtual C-suite for a new company, or when advisors lack company context — e.g. before a first /cs:boardroom or after a fundraise changes the numbers." --- # /cs:onboard — Founder Interview @@ -40,7 +40,9 @@ The first command to run when adopting c-level-agents. A structured founder inte ## Output Format -Saved to `~/.claude/company-context.md`: +**Canonical schema:** `~/.claude/company-context.md` is owned by the [`cs-onboard`](../../../skills/cs-onboard/SKILL.md) skill and follows its 7-dimension schema (`../../../skills/cs-onboard/templates/company-context-template.md`): Company Identity, Stage & Scale, Founder Profile, Team & Culture, Market & Competition, Current Challenges, Goals & Ambition. The 12 questions above are a faster structured intake that populates that same file — Identity/Business/Financial → Stage & Scale, Team → Team & Culture, Quarter priorities/risks → Current Challenges + Goals & Ambition. Write `[not captured]` for dimensions the quick intake doesn't reach (Founder Profile, Market & Competition); run the full `cs-onboard` interview to fill them. Never create a second context file or a divergent layout. + +The intake summary captured by the 12 questions: ```markdown # Company Context diff --git a/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md b/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md index 0bee3e88..37d7245a 100644 --- a/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/post-mortem/SKILL.md @@ -1,6 +1,6 @@ --- name: "post-mortem" -description: "/cs:post-mortem — Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop." +description: "/cs:post-mortem — Honest retrospective on an executed decision, scored against original assumptions and dissent. Closes the strategic sprint loop. Use when a decision hits its 90-day review checkpoint or its kill criteria trigger — e.g. scoring last quarter's pricing change against its pre-committed success metrics." --- # /cs:post-mortem — Honest Retrospective diff --git a/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md b/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md index c34c3770..ee73496d 100644 --- a/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md +++ b/c-level-advisor/c-level-agents/skills/vpe-review/SKILL.md @@ -1,6 +1,6 @@ --- name: "vpe-review" -description: "/cs:vpe-review — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline." +description: "/cs:vpe-review — Throughput-first VP of Engineering interrogation of any plan that touches delivery, eng hiring, team structure, or production discipline. Use when cycle time balloons, DORA metrics slide, or before committing to an eng hiring wave or a reorg." --- # /cs:vpe-review — VPE Forcing Questions @@ -112,7 +112,7 @@ python ../../../skills/vpe-advisor/scripts/eng_team_structure_designer.py team.j ## Routing - `/cs:cto-review` — for architectural causes of throughput problems -- `/cs:chro-review` — for hiring funnel comp/leveling issues +- `cs-chro-advisor` agent — for hiring funnel comp/leveling issues - `/cs:cfo-review` — for cost-per-hire envelope and eng budget - `/cs:ciso-review` — for production discipline + compliance overlap - `/cs:decide` — log the verdict diff --git a/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md b/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md index bf99009a..b1f9fac6 100644 --- a/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/hard-call/SKILL.md @@ -1,6 +1,6 @@ --- name: "hard-call" -description: "/em -hard-call — Framework for Decisions With No Good Options" +description: "/em:hard-call — Framework for decisions with no good options. Use when every option is painful and a structured 10/10/10 + regret-minimization pass is needed — e.g. choosing between a layoff and a down round, or killing a beloved product line." --- # /em:hard-call — Framework for Decisions With No Good Options diff --git a/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md b/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md index 20112c6c..32c2caf7 100644 --- a/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/postmortem/SKILL.md @@ -1,6 +1,6 @@ --- name: "postmortem" -description: "/em -postmortem — Honest Analysis of What Went Wrong" +description: "/em:postmortem — Honest analysis of what went wrong. Use after a failed launch, missed quarter, or bad hire to run a blameless 5-Whys retrospective with a change register — e.g. dissecting why the Q3 release slipped six weeks." --- # /em:postmortem — Honest Analysis of What Went Wrong diff --git a/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md b/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md index c39e0b65..39fac20f 100644 --- a/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md +++ b/c-level-advisor/executive-mentor/skills/stress-test/SKILL.md @@ -1,6 +1,6 @@ --- name: "stress-test" -description: "/em -stress-test — Business Assumption Stress Testing" +description: "/em:stress-test — Business assumption stress testing. Use before betting on a plan whose core assumptions are unvalidated — e.g. stress-testing 'enterprise buyers will tolerate a 6-month pilot' or a hockey-stick revenue model." --- # /em:stress-test — Business Assumption Stress Testing diff --git a/c-level-advisor/skills/agent-protocol/SKILL.md b/c-level-advisor/skills/agent-protocol/SKILL.md index 35ef75cd..b8576adf 100644 --- a/c-level-advisor/skills/agent-protocol/SKILL.md +++ b/c-level-advisor/skills/agent-protocol/SKILL.md @@ -34,7 +34,15 @@ Any agent can query another using: [INVOKE:cro|What does our pipeline look like for the next 90 days?] ``` -**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso` +**Valid roles:** `ceo`, `cfo`, `cro`, `cmo`, `cpo`, `cto`, `chro`, `coo`, `ciso`, `gc`, `cdo`, `caio`, `cco`, `vpe` + +| Role token | Advisor skill | +|---|---| +| `gc` | general-counsel-advisor (legal, contracts, term sheets) | +| `cdo` | chief-data-officer-advisor (data strategy, training-data rights) | +| `caio` | chief-ai-officer-advisor (AI strategy, evals, AI risk) | +| `cco` | chief-customer-officer-advisor (retention, customer success) | +| `vpe` | vpe-advisor (engineering delivery, DORA, eng hiring) | ## Response Format @@ -160,6 +168,26 @@ CEO can broadcast to all roles simultaneously: Responses come back independently (no agent sees another's response before forming its own). Aggregate after all respond. +## Decision Memory (Canonical Layout) + +All C-suite skills and `/cs:*` commands read and write decisions in **one** place — the two-layer model owned by `/cs:decide` and the decision-logger skill: + +``` +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1 — full transcripts/deliberations (never auto-loaded) +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2 — one founder-approved decision record per file +└── approved/decisions.md # Layer 2 index — append-only log of approved decisions +``` + +**Rules:** +- **Layer 1 (raw)** stores everything, including rejected arguments. Reference only — never feeds future sessions automatically. +- **Layer 2 (approved)** stores only founder-approved decisions. This is what board meetings, `/cs:office-hours`, and `/cs:founder-mode` load. Prevents hallucinated consensus. +- Writers: `/cs:decide` and the Chief of Staff (post board-meeting Phase 5). Individual role agents never write decisions directly. +- decision-logger, chief-of-staff, and board-meeting all use this layout. Their SKILL.md files link here rather than defining their own paths. + +**Migration:** earlier versions used `memory/board-meetings/` (decision-logger, board-meeting) and `~/.claude/decision-log.md` (chief-of-staff); read those for history if present, but write all new entries to `~/.claude/decisions/`. + ## Quick Reference | Rule | Behavior | @@ -217,6 +245,11 @@ When a recommendation impacts another role's domain, that role validates BEFORE | Customer-facing changes | CRO + CPO | Churn risk, product roadmap conflict | | Security or compliance claims | CISO | Actual posture, regulation requirements | | Market or positioning claims | CMO | Data backing, competitive reality | +| Legal exposure, contracts, term sheets | GC | Clause risk, IP ownership, regulatory triggers | +| Data rights, training-data provenance | CDO | Consent basis, GDPR Art. 6, data-asset impact | +| AI model claims, eval results, AI risk | CAIO | Eval coverage, hallucination SLO, EU AI Act tier | +| Retention, churn, customer-health claims | CCO | GRR/NRR decomposition, churn root cause | +| Delivery timelines, eng throughput | VPE | DORA metrics, cycle-time reality, team capacity | **Peer validation format:** ``` diff --git a/c-level-advisor/skills/board-deck-builder/SKILL.md b/c-level-advisor/skills/board-deck-builder/SKILL.md index 734a68ab..eb25bfc7 100644 --- a/c-level-advisor/skills/board-deck-builder/SKILL.md +++ b/c-level-advisor/skills/board-deck-builder/SKILL.md @@ -20,9 +20,10 @@ board deck, investor update, board meeting, board pack, investor relations, quar ## Quick Start -``` -/board-deck [quarterly|monthly|fundraising] [stage: seed|seriesA|seriesB] -``` +Ask for a board deck in natural language, naming cadence and stage: + +> "Build a quarterly board deck — we're Series A." +> "Draft a fundraising board deck for a seed-stage company." Provide available metrics. The builder fills gaps with explicit placeholders — never invents numbers. diff --git a/c-level-advisor/skills/board-meeting/SKILL.md b/c-level-advisor/skills/board-meeting/SKILL.md index ee85fa4b..1b4b0576 100644 --- a/c-level-advisor/skills/board-meeting/SKILL.md +++ b/c-level-advisor/skills/board-meeting/SKILL.md @@ -1,6 +1,6 @@ --- name: "board-meeting" -description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:board, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." +description: "Multi-agent board meeting protocol for strategic decisions. Runs a structured 6-phase deliberation: context loading, independent C-suite contributions (isolated, no cross-pollination), critic analysis, synthesis, founder review, and decision extraction. Use when the user invokes /cs:boardroom, calls a board meeting, or wants structured multi-perspective executive deliberation on a strategic question." license: MIT metadata: version: 1.0.0 @@ -16,29 +16,34 @@ metadata: Structured multi-agent deliberation that prevents groupthink, captures minority views, and produces clean, actionable decisions. ## Keywords -board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:board, founder review, decision extraction, independent perspectives +board meeting, executive deliberation, strategic decision, C-suite, multi-agent, /cs:boardroom, founder review, decision extraction, independent perspectives ## Invoke -`/cs:board [topic]` — e.g. `/cs:board Should we expand to Spain in Q3?` +`/cs:boardroom [topic]` — e.g. `/cs:boardroom Should we expand to Spain in Q3?` --- ## The 6-Phase Protocol ### PHASE 1: Context Gathering -1. Load `memory/company-context.md` -2. Load `memory/board-meetings/decisions.md` **(Layer 2 ONLY — never raw transcripts)** +1. Load `~/.claude/company-context.md` +2. Load Layer 2 approved decisions from `~/.claude/decisions/approved/` **(Layer 2 ONLY — never raw transcripts)** 3. Reset session state — no bleed from previous conversations 4. Present agenda + activated roles → wait for founder confirmation -**Chief of Staff selects relevant roles** based on topic (not all 9 every time): +**Chief of Staff selects relevant roles** based on topic (not all 14 every time): | Topic | Activate | |-------|----------| | Market expansion | CEO, CMO, CFO, CRO, COO | | Product direction | CEO, CPO, CTO, CMO | -| Hiring/org | CEO, CHRO, CFO, COO | +| Hiring/org | CEO, CHRO, CFO, COO (+ VPE for eng hiring) | | Pricing | CMO, CFO, CRO, CPO | | Technology | CTO, CPO, CFO, CISO | +| Contracts / term sheets / legal exposure | GC, CEO, CFO | +| Data strategy / training-data rights | CDO, CAIO, GC, CISO | +| AI strategy / model selection / AI risk | CAIO, CTO, CDO, CFO | +| Retention / churn / customer success | CCO, CRO, CPO | +| Eng delivery / DORA / team structure | VPE, CTO, CHRO, CFO | --- @@ -46,9 +51,9 @@ board meeting, executive deliberation, strategic decision, C-suite, multi-agent, **No cross-pollination. Each agent runs before seeing others' outputs.** -Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO +Order: Research (if needed) → CMO → CFO → CEO → CTO → COO → CHRO → CRO → CISO → CPO → GC → CDO → CAIO → CCO → VPE (activated roles only) -**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data +**Reasoning techniques:** CEO: Tree of Thought (3 futures) | CFO: Chain of Thought (show the math) | CMO: Recursion of Thought (draft→critique→refine) | CPO: First Principles | CRO: Chain of Thought (pipeline math) | COO: Step by Step (process map) | CTO: ReAct (research→analyze→act) | CISO: Risk-Based (P×I) | CHRO: Empathy + Data | GC: Risk-Based (clause exposure) | CDO: Decision-Driven (what decision does this data drive) | CAIO: Eval-Demanding (no eval, no ship) | CCO: Retention-Obsessed (GRR over NRR) | VPE: Throughput-First (cycle-time math) **Contribution format (max 5 key points, self-verified):** ``` @@ -104,29 +109,35 @@ Options: ✅ Approve | ✏️ Modify | ❌ Reject | ❓ Ask follow-up **Rules:** - User corrections OVERRIDE agent proposals. No pushback. No "but the CFO said..." - 30-min inactivity → auto-close as "pending review" -- Reopen any time with `/cs:board resume` +- Reopen any time with `/cs:boardroom resume` --- ### PHASE 6: Decision Extraction After founder approval: -- **Layer 1:** Write full transcript → `memory/board-meetings/YYYY-MM-DD-raw.md` -- **Layer 2:** Append approved decisions → `memory/board-meetings/decisions.md` +- **Layer 1:** Write full transcript → `~/.claude/decisions/raw/YYYY-MM-DD-.md` +- **Layer 2:** Write approved decision record → `~/.claude/decisions/approved/YYYY-MM-DD-.md` and append to the index `~/.claude/decisions/approved/decisions.md` - Mark rejected proposals `[DO_NOT_RESURFACE]` - Confirm to founder with count of decisions logged, actions tracked, flags added --- ## Memory Structure + +Uses the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"): + ``` -memory/board-meetings/ -├── decisions.md # Layer 2 — founder-approved only (Phase 1 loads this) -├── YYYY-MM-DD-raw.md # Layer 1 — full transcripts (never auto-loaded) -└── archive/YYYY/ # Raw transcripts after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1 — full transcripts (never auto-loaded) +├── raw/archive/YYYY/ # Raw transcripts after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2 — founder-approved records (Phase 1 loads these) +└── approved/decisions.md # Layer 2 index — append-only ``` **Future meetings load Layer 2 only.** Never Layer 1. This prevents hallucinated consensus. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write new transcripts and decisions to `~/.claude/decisions/`. + --- ## Failure Mode Quick Reference @@ -136,7 +147,7 @@ memory/board-meetings/ | Analysis paralysis | Cap at 5 points; force recommendation even with Low confidence | | Bikeshedding | Log as async action item; return to main agenda | | Role bleed (CFO making product calls) | Critic flags; exclude from synthesis | -| Layer contamination | Phase 1 loads decisions.md only — hard rule | +| Layer contamination | Phase 1 loads `~/.claude/decisions/approved/` only — hard rule | --- diff --git a/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md b/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md index 60437d8a..7d73254e 100644 --- a/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md +++ b/c-level-advisor/skills/board-meeting/references/meeting-facilitation.md @@ -164,4 +164,4 @@ After each board meeting, score it: | Roles activated | 3–6 | All 9 (too many = noise) | | Phase 2 conflicts surfaced | At least 1 | 0 (groupthink risk) | -Track these in `memory/board-meetings/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken. +Track these in `~/.claude/decisions/meeting-health.md` over time. Pattern: if action items consistently exceed 8, meetings are too infrequent. If conflicts are consistently 0, isolation is broken. diff --git a/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md b/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md index b491937f..51896634 100644 --- a/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md +++ b/c-level-advisor/skills/board-meeting/templates/meeting-agenda.md @@ -1,7 +1,7 @@ # Board Meeting Agenda Template -Use this to structure a board meeting before invoking `/cs:board`. -Paste it into the conversation or save it as `memory/board-meetings/agenda-YYYY-MM-DD.md`. +Use this to structure a board meeting before invoking `/cs:boardroom`. +Paste it into the conversation or save it as `~/.claude/decisions/agenda-YYYY-MM-DD.md`. --- @@ -70,7 +70,7 @@ List topics that might come up but are NOT on today's agenda: ## Pre-Read Materials all participants should review before the meeting: -- [ ] `memory/board-meetings/decisions.md` (Chief of Staff loads automatically) +- [ ] `~/.claude/decisions/approved/decisions.md` (Chief of Staff loads automatically) - [ ] [Link or filename] - [ ] [Link or filename] diff --git a/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md b/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md index bd165e6b..d41db40c 100644 --- a/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md +++ b/c-level-advisor/skills/board-meeting/templates/meeting-minutes.md @@ -2,9 +2,9 @@ This is the Layer 2 output — the founder-approved record of what was decided. Written by Chief of Staff after Phase 5 (founder approval). -Appended to `memory/board-meetings/decisions.md`. +Appended to the Layer 2 index `~/.claude/decisions/approved/decisions.md`. -Do NOT include raw agent debate here. That lives in `YYYY-MM-DD-raw.md` (Layer 1). +Do NOT include raw agent debate here. That lives in `~/.claude/decisions/raw/YYYY-MM-DD-.md` (Layer 1). --- @@ -88,4 +88,4 @@ These were not resolved in this meeting. They carry forward. --- *Minutes approved by: [Founder name] on [DATE]* -*Raw transcript: `memory/board-meetings/[DATE]-raw.md`* +*Raw transcript: `~/.claude/decisions/raw/[DATE]-.md`* diff --git a/c-level-advisor/skills/c-level-skills/SKILL.md b/c-level-advisor/skills/c-level-skills/SKILL.md index 5deb724d..7e40a382 100644 --- a/c-level-advisor/skills/c-level-skills/SKILL.md +++ b/c-level-advisor/skills/c-level-skills/SKILL.md @@ -1,153 +1,47 @@ --- -name: "c-level-advisor" -description: "10 C-level advisory agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor. Multi-role board meetings, strategy routing, structured recommendations. For founders needing executive-level decision support." +name: "c-level-skills" +description: "Index and router for the C-level advisory bundle: 33 skills covering 14 C-suite roles, orchestration, cross-cutting capabilities, and culture. Use when exploring what the c-level-advisor bundle contains, deciding which advisor skill fits a question, or finding the entry points (cs-onboard interview, chief-of-staff routing, board-meeting protocol)." license: MIT metadata: - version: 2.0.0 + version: 2.1.0 author: Alireza Rezvani category: c-level domain: executive-advisory - updated: 2026-03-05 - skills_count: 28 - scripts_count: 25 - references_count: 52 + updated: 2026-06-11 + skills_count: 33 + scripts_count: 37 + references_count: 68 --- -# C-Level Advisory Ecosystem +# C-Level Advisory Bundle — Index -A complete virtual board of directors for founders and executives. +This is the bundle index, not an advisor. It tells you what exists and where to start; the skills below do the work. -## Quick Start +## Start Here -``` -1. Run /cs:setup → creates company-context.md (all agents read this) - ✓ Verify company-context.md was created and contains your company name, - stage, and core metrics before proceeding. -2. Ask any strategic question → Chief of Staff routes to the right role -3. For big decisions → /cs:board triggers a multi-role board meeting - ✓ Confirm at least 3 roles have weighed in before accepting a conclusion. -``` +1. **Onboard** — the `cs-onboard` skill runs the founder interview (`/cs:setup`, 7 dimensions, ~45 min) and writes `~/.claude/company-context.md`. Refresh quarterly with `/cs:update`. This is the canonical context schema every advisor reads. +2. **Ask** — the `chief-of-staff` skill routes any question to the right advisor(s). See its routing matrix for all 14 roles. +3. **Big decisions** — the `board-meeting` skill runs a **6-phase** deliberation: (1) context gathering → (2) independent contributions (isolated) → (3) critic analysis → (4) synthesis → (5) founder review (full stop) → (6) decision extraction. Invoked via `/cs:boardroom` in the c-level-agents plugin. +4. **Memory** — decisions land in the canonical two-layer layout `~/.claude/decisions/{raw,approved}/` (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"). -### Commands +## What's in the Bundle (33 skills) -#### `/cs:setup` — Onboarding Questionnaire +**14 C-suite roles + critic (15):** ceo-advisor, cfo-advisor, cto-advisor, coo-advisor, cpo-advisor, cmo-advisor, cro-advisor, ciso-advisor, chro-advisor, general-counsel-advisor, chief-data-officer-advisor, chief-ai-officer-advisor, chief-customer-officer-advisor, vpe-advisor — plus the executive-mentor critic (sibling plugin). -Walks through the following prompts and writes `company-context.md` to the project root. Run once per company or when context changes significantly. +**Orchestration (6):** cs-onboard, chief-of-staff, board-meeting, decision-logger, agent-protocol, context-engine. -``` -Q1. What is your company name and one-line description? -Q2. What stage are you at? (Idea / Pre-seed / Seed / Series A / Series B+) -Q3. What is your current ARR (or MRR) and runway in months? -Q4. What is your team size and structure? -Q5. What industry and customer segment do you serve? -Q6. What are your top 3 priorities for the next 90 days? -Q7. What is your biggest current risk or blocker? -``` +**Cross-cutting (6):** board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion. -After collecting answers, the agent writes structured output: +**Culture & collaboration (6):** culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative. -```markdown -# Company Context -- Name: -- Stage: -- Industry: -- Team size: -- Key metrics: -- Top priorities: -- Key risks: -``` +Plus this index (1). 37 stdlib-only Python tools and 68 reference docs across the bundle. -#### `/cs:board` — Full Board Meeting +## Routing Quick Reference -Convenes all relevant executive roles in three phases: +Full matrix in `../chief-of-staff/SKILL.md` and `../chief-of-staff/references/routing-matrix.md`. Primary roles: CFO (capital/burn), CRO (pipeline/sales), CMO (positioning), CPO (roadmap/PMF), CTO (architecture), COO (ops/OKRs), CHRO (people), CISO (security), GC (contracts/term sheets), CDO (data strategy/training-data rights), CAIO (AI strategy/evals), CCO (retention/GRR), VPE (delivery/DORA), CEO (direction). Multi-domain or irreversible → board meeting. -``` -Phase 1 — Framing: Chief of Staff states the decision and success criteria. -Phase 2 — Isolation: Each role produces independent analysis (no cross-talk). -Phase 3 — Debate: Roles surface conflicts, stress-test assumptions, align on - a recommendation. Dissenting views are preserved in the log. -``` +## Related Layers -Use for high-stakes or cross-functional decisions. Confirm at least 3 roles have weighed in before accepting a conclusion. - -### Chief of Staff Routing Matrix - -When a question arrives without a role prefix, the Chief of Staff maps it to the appropriate executive using these primary signals: - -| Topic Signal | Primary Role | Supporting Roles | -|---|---|---| -| Fundraising, valuation, burn | CFO | CEO, CRO | -| Architecture, build vs. buy, tech debt | CTO | CPO, CISO | -| Hiring, culture, performance | CHRO | CEO, Executive Mentor | -| GTM, demand gen, positioning | CMO | CRO, CPO | -| Revenue, pipeline, sales motion | CRO | CMO, CFO | -| Security, compliance, risk | CISO | CTO, CFO | -| Product roadmap, prioritisation | CPO | CTO, CMO | -| Ops, process, scaling | COO | CFO, CHRO | -| Vision, strategy, investor relations | CEO | Executive Mentor | -| Career, founder psychology, leadership | Executive Mentor | CEO, CHRO | -| Multi-domain / unclear | Chief of Staff convenes board | All relevant roles | - -### Invoking a Specific Role Directly - -To bypass Chief of Staff routing and address one executive directly, prefix your question with the role name: - -``` -CFO: What is our optimal burn rate heading into a Series A? -CTO: Should we rebuild our auth layer in-house or buy a solution? -CHRO: How do we design a performance review process for a 15-person team? -``` - -The Chief of Staff still logs the exchange; only routing is skipped. - -### Example: Strategic Question - -**Input:** "Should we raise a Series A now or extend runway and grow ARR first?" - -**Output format:** -- **Bottom Line:** Extend runway 6 months; raise at $2M ARR for better terms. -- **What:** Current $800K ARR is below the threshold most Series A investors benchmark. -- **Why:** Raising now increases dilution risk; 6-month extension is achievable with current burn. -- **How to Act:** Cut 2 low-ROI channels, hit $2M ARR, then run a 6-week fundraise sprint. -- **Your Decision:** Proceed with extension / Raise now anyway (choose one). - -### Example: company-context.md (after /cs:setup) - -```markdown -# Company Context -- Name: Acme Inc. -- Stage: Seed ($800K ARR) -- Industry: B2B SaaS -- Team size: 12 -- Key metrics: 15% MoM growth, 18-month runway -- Top priorities: Series A readiness, enterprise GTM -``` - -## What's Included - -### 10 C-Suite Roles -CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor - -### 6 Orchestration Skills -Founder Onboard, Chief of Staff (router), Board Meeting, Decision Logger, Agent Protocol, Context Engine - -### 6 Cross-Cutting Capabilities -Board Deck Builder, Scenario War Room, Competitive Intel, Org Health Diagnostic, M&A Playbook, International Expansion - -### 6 Culture & Collaboration -Culture Architect, Company OS, Founder Coach, Strategic Alignment, Change Management, Internal Narrative - -## Key Features - -- **Internal Quality Loop:** Self-verify → peer-verify → critic pre-screen → present -- **Two-Layer Memory:** Raw transcripts + approved decisions only (prevents hallucinated consensus) -- **Board Meeting Isolation:** Phase 2 independent analysis before cross-examination -- **Proactive Triggers:** Context-driven early warnings without being asked -- **Structured Output:** Bottom Line → What → Why → How to Act → Your Decision -- **25 Python Tools:** All stdlib-only, CLI-first, JSON output, zero dependencies - -## See Also - -- `CLAUDE.md` — full architecture diagram and integration guide -- `../agent-protocol/SKILL.md` — communication standard and quality loop details -- `../chief-of-staff/SKILL.md` — routing matrix for all 28 skills +- `../../c-level-agents/` — 13 cs-* persona agents + 21 `/cs:*` slash commands on top of these skills +- `../../executive-mentor/` — adversarial `/em:*` critic commands +- `../../CLAUDE.md` — full architecture diagram and integration guide diff --git a/c-level-advisor/skills/chief-of-staff/SKILL.md b/c-level-advisor/skills/chief-of-staff/SKILL.md index 2e0bc135..9dfb8953 100644 --- a/c-level-advisor/skills/chief-of-staff/SKILL.md +++ b/c-level-advisor/skills/chief-of-staff/SKILL.md @@ -1,6 +1,6 @@ --- name: "chief-of-staff" -description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically." +description: "C-suite orchestration layer. Routes founder questions to the right advisor role(s), triggers multi-role board meetings for complex decisions, synthesizes outputs, and tracks decisions. Every C-suite interaction starts here. Loads company context automatically. Use when a founder question needs routing to the right advisor — e.g. 'should we raise now or cut burn?' — or when a multi-domain decision needs a board meeting convened." license: MIT metadata: version: 1.0.0 @@ -81,6 +81,11 @@ Full rules in `references/routing-matrix.md`. | Company direction, investor relations | CEO | Board | | Market strategy, positioning | CMO | CRO | | M&A, pivots | CEO | Board | +| Contracts, term sheets, legal exposure, IP | GC | CEO | +| Data strategy, training-data rights, data assets | CDO | CAIO | +| AI strategy, model selection, evals, AI risk | CAIO | CTO | +| Retention, churn, customer success, NRR/GRR | CCO | CRO | +| Eng delivery, DORA metrics, eng hiring, team structure | VPE | CTO | --- @@ -133,7 +138,10 @@ Full framework in `references/synthesis-framework.md`. ## Decision Log -Track decisions to `~/.claude/decision-log.md`. +Track decisions using the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)"): + +- **Layer 1 (raw):** `~/.claude/decisions/raw/YYYY-MM-DD-{slug}.md` — full deliberation transcript +- **Layer 2 (approved):** `~/.claude/decisions/approved/YYYY-MM-DD-{slug}.md` — founder-approved decisions only ``` ## Decision: [Name] @@ -144,7 +152,9 @@ Owner: [Who executes] Review: [When to check back] ``` -At session start: if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* +At session start: scan `~/.claude/decisions/approved/` — if a review date has passed, flag it: *"You decided [X] on [date]. Worth a check-in?"* + +Migration: a legacy single-file log at `~/.claude/decision-log.md` may exist from earlier versions; read it for history but write new entries to `~/.claude/decisions/`. --- @@ -166,9 +176,9 @@ Before delivering ANY output to the founder: ## Ecosystem Awareness -The Chief of Staff routes to **28 skills total**: -- **10 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, Executive Mentor -- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol +The Chief of Staff routes to **33 skills total**: +- **15 C-suite roles** — CEO, CTO, COO, CPO, CMO, CFO, CRO, CISO, CHRO, General Counsel, CDO, CAIO, CCO, VPE, Executive Mentor +- **6 orchestration skills** — cs-onboard, context-engine, board-meeting, decision-logger, agent-protocol, chief-of-staff - **6 cross-cutting skills** — board-deck-builder, scenario-war-room, competitive-intel, org-health-diagnostic, ma-playbook, intl-expansion - **6 culture & collaboration skills** — culture-architect, company-os, founder-coach, strategic-alignment, change-management, internal-narrative diff --git a/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md b/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md index 2c94ac08..4048f57c 100644 --- a/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md +++ b/c-level-advisor/skills/chief-of-staff/references/routing-matrix.md @@ -102,6 +102,52 @@ Detailed routing rules for the Chief of Staff. When a founder asks a question, f | What's our security posture? | CISO | CTO | 1 | | A regulator is asking questions | CISO | CEO, COO | 4 | +### Legal & Contracts + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Is this contract safe to sign? | GC | CFO | 2 | +| What's wrong with this term sheet? | GC | CFO, CEO | 3 | +| Do we own the IP our contractors wrote? | GC | CTO | 2 | +| A customer wants an MSA redline — what matters? | GC | CRO | 2 | +| Are we exposed on data privacy / GDPR? | GC | CISO, CDO | 3 | + +### Data Strategy + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Can we train models on our customer data? | CDO | GC, CAIO | 3 | +| Warehouse, lakehouse, or mesh? | CDO | CTO | 2 | +| Is our data an asset we can productize or sell? | CDO | CFO, GC | 3 | +| How do we value our data in M&A diligence? | CDO | CFO | 3 | + +### AI Strategy + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Should we use an API, fine-tune, or build our own model? | CAIO | CTO, CFO | 3 | +| What does the EU AI Act mean for this feature? | CAIO | GC, CISO | 3 | +| Our AI costs are exploding — what now? | CAIO | CFO | 2 | +| How do we eval / set a hallucination SLO? | CAIO | CTO | 2 | + +### Customer & Retention + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Gross retention dropped — why? | CCO | CRO, CPO | 3 | +| How many CSMs do we need per ARR tier? | CCO | CFO, CHRO | 2 | +| Which customers should we fire? | CCO | CRO | 2 | +| NRR looks fine but logos keep leaving | CCO | CRO, CPO | 3 | + +### Engineering Delivery + +| Question type | Primary | Secondary | Score | +|--------------|---------|-----------|-------| +| Why is shipping so slow? (cycle time, DORA) | VPE | CTO | 2 | +| How should we structure eng teams at this headcount? | VPE | CHRO | 2 | +| Our eng hiring funnel is leaking — where? | VPE | CHRO | 2 | +| Eng delivery vs architecture debt trade-off | VPE | CTO, CPO | 3 | + ### Strategic Direction | Question type | Primary | Secondary | Score | @@ -165,6 +211,11 @@ Automatically escalate to board meeting when any of these apply: | CMO | cmo-advisor | Marketing, brand, positioning | | CHRO | chro-advisor | People, culture, hiring | | CISO | ciso-advisor | Security, compliance, risk | +| GC | general-counsel-advisor | Legal, contracts, term sheets, IP | +| CDO | chief-data-officer-advisor | Data strategy, training-data rights, data assets | +| CAIO | chief-ai-officer-advisor | AI strategy, model selection, evals, AI risk | +| CCO | chief-customer-officer-advisor | Retention, churn, customer success | +| VPE | vpe-advisor | Eng delivery, DORA, eng hiring, team structure | **If a role file doesn't exist:** Note the gap. Answer from first principles with domain expertise. Log that the role is missing. @@ -179,7 +230,7 @@ These skills are invoked for specific cross-cutting needs, not for general domai |-------|---------|------| | C-Suite Onboard | `/cs:setup`, first-time setup, "tell me about your company" | cs-onboard | | Context Engine | Auto-loaded; staleness check | context-engine | -| Board Meeting | `/cs:board`, multi-role decisions, score ≥ 4 | board-meeting | +| Board Meeting | `/cs:boardroom`, multi-role decisions, score ≥ 4 | board-meeting | | Decision Logger | After board meetings, `/cs:decisions`, `/cs:review` | decision-logger | | Agent Protocol | Inter-role invocations, loop detection | agent-protocol | diff --git a/c-level-advisor/skills/competitive-intel/SKILL.md b/c-level-advisor/skills/competitive-intel/SKILL.md index ef4223d8..49036073 100644 --- a/c-level-advisor/skills/competitive-intel/SKILL.md +++ b/c-level-advisor/skills/competitive-intel/SKILL.md @@ -20,13 +20,13 @@ competitive intelligence, competitor analysis, battlecard, win/loss analysis, co ## Quick Start -``` -/ci:landscape — Map your competitive space (direct, indirect, future) -/ci:battlecard [name] — Build a sales battlecard for a specific competitor -/ci:winloss — Analyze recent wins and losses by reason -/ci:update [name] — Track what a competitor did recently -/ci:map — Build competitive positioning map -``` +Ask in natural language for the deliverable you need: + +> "Map our competitive landscape" — direct, indirect, and future competitors +> "Build a battlecard for [competitor]" — sales-ready battlecard +> "Run a win/loss analysis" — recent wins and losses by reason +> "What did [competitor] do recently?" — competitor update tracking +> "Build a competitive positioning map" — 2x2 positioning map ## Framework: 5-Layer Intelligence System diff --git a/c-level-advisor/skills/context-engine/SKILL.md b/c-level-advisor/skills/context-engine/SKILL.md index 4d99a510..b29d5625 100644 --- a/c-level-advisor/skills/context-engine/SKILL.md +++ b/c-level-advisor/skills/context-engine/SKILL.md @@ -1,6 +1,6 @@ --- name: "context-engine" -description: "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls." +description: "Loads and manages company context for all C-suite advisor skills. Reads ~/.claude/company-context.md, detects stale context (>90 days), enriches context during conversations, and enforces privacy/anonymization rules before external API calls. Use when starting any C-suite advisor session, when context looks stale or missing, or before sending company data to an external service." license: MIT metadata: version: 1.0.0 diff --git a/c-level-advisor/skills/cs-onboard/SKILL.md b/c-level-advisor/skills/cs-onboard/SKILL.md index 3ad0c7fa..e908b96a 100644 --- a/c-level-advisor/skills/cs-onboard/SKILL.md +++ b/c-level-advisor/skills/cs-onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: "cs-onboard" -description: "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills." +description: "Founder onboarding interview that captures company context across 7 dimensions. Invoke with /cs:setup for initial interview or /cs:update for quarterly refresh. Generates ~/.claude/company-context.md used by all C-suite advisor skills. Use when setting up the C-suite advisors for the first time, or when company context is missing or more than 90 days old — e.g. after a fundraise or pivot." license: MIT metadata: version: 1.0.0 diff --git a/c-level-advisor/skills/decision-logger/SKILL.md b/c-level-advisor/skills/decision-logger/SKILL.md index b29c2694..b5245622 100644 --- a/c-level-advisor/skills/decision-logger/SKILL.md +++ b/c-level-advisor/skills/decision-logger/SKILL.md @@ -46,20 +46,24 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions ## Two-Layer Architecture +Storage follows the canonical two-layer decision memory (see `../agent-protocol/SKILL.md` → "Decision Memory (Canonical Layout)") — the same layout `/cs:decide` writes. + ### Layer 1 — Raw Transcripts -**Location:** `memory/board-meetings/YYYY-MM-DD-raw.md` +**Location:** `~/.claude/decisions/raw/YYYY-MM-DD-.md` - Full Phase 2 agent contributions, Phase 3 critique, Phase 4 synthesis - All debates, including rejected arguments - **NEVER auto-loaded.** Only on explicit founder request. -- Archive after 90 days → `memory/board-meetings/archive/YYYY/` +- Archive after 90 days → `~/.claude/decisions/raw/archive/YYYY/` ### Layer 2 — Approved Decisions -**Location:** `memory/board-meetings/decisions.md` +**Location:** `~/.claude/decisions/approved/` — one record per decision (`YYYY-MM-DD-.md`) plus the append-only index `decisions.md` - ONLY founder-approved decisions, action items, user corrections - **Loaded automatically in Phase 1 of every board meeting** - Append-only. Decisions are never deleted — only superseded. - Managed by Chief of Staff after Phase 5. Never written by agents directly. +Migration: a legacy `memory/board-meetings/` folder may exist from earlier versions; read it for history but write all new entries to `~/.claude/decisions/`. + --- ## Decision Entry Format @@ -83,7 +87,7 @@ python scripts/decision_tracker.py --search "pricing" # Search decisions **Supersedes:** [DATE of previous decision on same topic, if any] **Superseded by:** [Filled in retroactively if overridden later] -**Raw transcript:** memory/board-meetings/[DATE]-raw.md +**Raw transcript:** ~/.claude/decisions/raw/[DATE]-.md ``` --- @@ -115,10 +119,10 @@ To reopen: founder must explicitly say "reopen [topic] from [DATE]". ## Logging Workflow (Post Phase 5) 1. Founder approves synthesis -2. Write Layer 1 raw transcript → `YYYY-MM-DD-raw.md` -3. Check conflicts against `decisions.md` +2. Write Layer 1 raw transcript → `~/.claude/decisions/raw/YYYY-MM-DD-.md` +3. Check conflicts against `~/.claude/decisions/approved/decisions.md` 4. Surface conflicts → wait for founder resolution -5. Append approved entries to `decisions.md` +5. Write the approved record to `~/.claude/decisions/approved/YYYY-MM-DD-.md` and append to the index `decisions.md` 6. Confirm: decisions logged, actions tracked, DO_NOT_RESURFACE flags added --- @@ -136,10 +140,11 @@ Never delete completed items. The history is the record. ## File Structure ``` -memory/board-meetings/ -├── decisions.md # Layer 2: append-only, founder-approved -├── YYYY-MM-DD-raw.md # Layer 1: full transcript per meeting -└── archive/YYYY/ # Raw files after 90 days +~/.claude/decisions/ +├── raw/YYYY-MM-DD-.md # Layer 1: full transcript per meeting +├── raw/archive/YYYY/ # Raw files after 90 days +├── approved/YYYY-MM-DD-.md # Layer 2: one record per approved decision +└── approved/decisions.md # Layer 2 index: append-only, founder-approved ``` --- diff --git a/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py b/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py index 7a9020df..36a68983 100644 --- a/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py +++ b/c-level-advisor/skills/decision-logger/scripts/decision_tracker.py @@ -3,7 +3,8 @@ decision_tracker.py — Board Meeting Decision Parser & Reporter Part of the C-Level Advisor / Decision Logger skill. -Parses memory/board-meetings/decisions.md and produces actionable reports. +Parses the Layer 2 index ~/.claude/decisions/approved/decisions.md and produces actionable reports. +(Legacy location memory/board-meetings/decisions.md still works via --file.) Stdlib only. No dependencies. Usage: @@ -471,7 +472,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-02-15-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-02-15-pricing-tier-restructure.md --- @@ -496,7 +497,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-02-28-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-02-28-enterprise-sales-hire.md --- @@ -521,7 +522,7 @@ This file contains ONLY founder-approved decisions. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/2026-03-04-raw.md +**Raw transcript:** ~/.claude/decisions/raw/2026-03-04-eu-expansion.md """ @@ -537,7 +538,7 @@ def load_decisions(decisions_path: Path, demo: bool) -> list[Decision]: else: print(f" ⚠️ decisions.md not found at: {decisions_path}") print(f" Run with --demo to see sample output.") - print(f" To initialize: mkdir -p memory/board-meetings && touch memory/board-meetings/decisions.md") + print(f" To initialize: mkdir -p ~/.claude/decisions/approved && touch ~/.claude/decisions/approved/decisions.md") sys.exit(1) return parse_decisions(content) @@ -548,8 +549,8 @@ def main(): formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - parser.add_argument("--file", default="memory/board-meetings/decisions.md", - help="Path to decisions.md (default: memory/board-meetings/decisions.md)") + parser.add_argument("--file", default=os.path.expanduser("~/.claude/decisions/approved/decisions.md"), + help="Path to decisions.md (default: ~/.claude/decisions/approved/decisions.md)") parser.add_argument("--demo", action="store_true", help="Run with built-in sample data (no file needed)") parser.add_argument("--summary", action="store_true", diff --git a/c-level-advisor/skills/decision-logger/templates/decision-entry.md b/c-level-advisor/skills/decision-logger/templates/decision-entry.md index e83a2af7..0412fa80 100644 --- a/c-level-advisor/skills/decision-logger/templates/decision-entry.md +++ b/c-level-advisor/skills/decision-logger/templates/decision-entry.md @@ -1,6 +1,6 @@ # Decision Entry Template -Single entry for `memory/board-meetings/decisions.md`. +Single entry for the Layer 2 index `~/.claude/decisions/approved/decisions.md`. Copy this block and fill it in after each approved board decision. --- @@ -32,7 +32,7 @@ Copy this block and fill it in after each approved board decision. **Supersedes:** **Superseded by:** -**Raw transcript:** memory/board-meetings/[YYYY-MM-DD]-raw.md +**Raw transcript:** ~/.claude/decisions/raw/[YYYY-MM-DD]-.md ``` --- diff --git a/c-level-advisor/skills/ma-playbook/SKILL.md b/c-level-advisor/skills/ma-playbook/SKILL.md index 4abdeafe..a5b4f86a 100644 --- a/c-level-advisor/skills/ma-playbook/SKILL.md +++ b/c-level-advisor/skills/ma-playbook/SKILL.md @@ -41,10 +41,15 @@ M&A, mergers and acquisitions, due diligence, acquisition, acqui-hire, integrati | Customers | Churn rate, NPS, contract terms | High churn, short contracts | ### Valuation Approaches -- **Revenue multiple:** Industry-dependent (2-15x ARR for SaaS) -- **Comparable transactions:** What similar companies sold for + +The ranges below are **illustrative, not current market data** — always verify against current market comps before using them in a model or negotiation. + +- **Revenue multiple:** Industry-dependent (illustrative range: 2-15x ARR for SaaS, varying with growth rate, NRR, and rate environment) +- **Comparable transactions:** What similar companies sold for — the most defensible anchor - **DCF:** For profitable companies only (most startups: use multiples) -- **Acqui-hire:** $1-3M per engineer in hot markets +- **Acqui-hire:** Illustrative range: $1-3M per engineer in hot talent markets + +**Sources to verify against (check the latest edition):** the SaaS Capital Index (private SaaS revenue multiples, updated monthly), Software Equity Group (SEG) Annual/Quarterly SaaS M&A Reports (transaction multiples), and Aventis Advisors' SaaS valuation multiples reports. Cross-check at least two before anchoring a price. ### Integration Frameworks See `references/integration-playbook.md` for the 100-day integration plan. @@ -82,12 +87,24 @@ See `references/integration-playbook.md` for the 100-day integration plan. - Integration plan doesn't exist or is "we'll figure it out" - Valuation based on projections, not actuals +## Verification Loop (before any LOI or signature) + +This skill frames the deal; two sibling skills verify it. Hand off — don't duplicate: + +1. **Legal terms** → `general-counsel-advisor`: run the LOI/term sheet through `../general-counsel-advisor/scripts/term_sheet_analyzer.py` (12-dimension 0-100 score) and the definitive docs through `../general-counsel-advisor/scripts/contract_risk_scanner.py` (12 founder-killer patterns: earnout traps, uncapped indemnity, vague IP, etc.). Any 🔴 finding goes to outside counsel before signing. +2. **Data diligence** → `chief-data-officer-advisor`: run `../chief-data-officer-advisor/scripts/ai_training_data_audit.py` (training-data rights, GDPR Art. 6 basis) and `../chief-data-officer-advisor/scripts/data_asset_valuator.py` (data-asset value, M&A multiplier with carve-out penalties) on the target's data estate. Undocumented consent provenance is a price-reduction or walk-away item. +3. **Valuation math** → `cfo-advisor` tools for the quantitative model; this playbook stays qualitative. + +Loop the findings back into the negotiation-points table above before the next counter. + ## Integration with C-Suite Roles | Role | Contribution to M&A | |------|-------------------| | CEO | Strategic rationale, negotiation lead | | CFO | Valuation, deal structure, financing | +| GC | LOI/term sheet review, contract risk scan, regulatory triggers | +| CDO | Data diligence: training-data rights, data-asset valuation | | CTO | Technical due diligence, integration architecture | | CHRO | People due diligence, retention planning | | COO | Integration execution, process merge | @@ -96,3 +113,5 @@ See `references/integration-playbook.md` for the 100-day integration plan. ## Resources - `references/integration-playbook.md` — 100-day post-acquisition integration plan - `references/due-diligence-checklist.md` — comprehensive DD checklist by domain +- `../general-counsel-advisor/SKILL.md` — term sheet analyzer + contract risk scanner +- `../chief-data-officer-advisor/SKILL.md` — data diligence + data-asset valuation diff --git a/c-level-advisor/skills/org-health-diagnostic/SKILL.md b/c-level-advisor/skills/org-health-diagnostic/SKILL.md index a1c36d9b..ff1af94c 100644 --- a/c-level-advisor/skills/org-health-diagnostic/SKILL.md +++ b/c-level-advisor/skills/org-health-diagnostic/SKILL.md @@ -26,11 +26,10 @@ python scripts/health_scorer.py # Guided CLI — enter metrics, get score python scripts/health_scorer.py --json # Output raw JSON for integration ``` -Or describe your metrics: -``` -/health [paste your key metrics or answer prompts] -/health:dimension [financial|revenue|product|engineering|people|ops|security|market] -``` +Or describe your metrics in natural language: + +> "Run an org health check" — paste your key metrics or answer prompts +> "Score our [financial|revenue|product|engineering|people|ops|security|market] health" — single-dimension deep dive ## The 8 Dimensions diff --git a/c-level-advisor/skills/scenario-war-room/SKILL.md b/c-level-advisor/skills/scenario-war-room/SKILL.md index ad6c5428..d52e33ea 100644 --- a/c-level-advisor/skills/scenario-war-room/SKILL.md +++ b/c-level-advisor/skills/scenario-war-room/SKILL.md @@ -25,12 +25,11 @@ scenario planning, war room, what-if analysis, risk modeling, cascading effects, python scripts/scenario_modeler.py # Interactive scenario builder with cascade modeling ``` -Or describe the scenario: -``` -/war-room "What if we lose our top customer AND miss the Q3 fundraise?" -/war-room "What if 3 engineers quit AND we need to ship by Q3?" -/war-room "What if our market shrinks 30% AND a competitor raises $50M?" -``` +Or describe the scenario in natural language: + +> "What if we lose our top customer AND miss the Q3 fundraise?" +> "What if 3 engineers quit AND we need to ship by Q3?" +> "What if our market shrinks 30% AND a competitor raises $50M?" ## What This Is Not diff --git a/commercial/skills/channel-economics/SKILL.md b/commercial/skills/channel-economics/SKILL.md index cf4c6f2c..9a7cbe73 100644 --- a/commercial/skills/channel-economics/SKILL.md +++ b/commercial/skills/channel-economics/SKILL.md @@ -1,6 +1,6 @@ --- name: channel-economics -description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection. Not channel structure (that's partnerships-architect — tiers, joint GTM, revshare). Not RevOps process (that's business-growth/revenue-operations — lead routing, SDR motion). Not strategic CRO judgment (that's c-level-advisor/cro-advisor — comp plans, when-to-hire-a-VP-Sales). Not historical close-and-report (that's finance/financial-analysis). This skill answers: direct vs partner profitability, channel profitability, channel mix, channel economics." +description: "Use when reviewing or rebalancing direct vs. partner-led channel economics — computing fully-loaded cost-to-serve per channel, channel ROI with cash / LTV / marginal lenses, and optimal channel mix subject to constraints. For Head of Commercial, RevOps, and VP Sales doing quarterly channel review when pipeline is mixed (e.g., 60% direct + 40% partner-led) and nobody actually knows which channel makes money after CAC, support load, partner discount, deal-velocity differences, retention differential, and overhead allocation are all loaded in. Outputs cost to serve, channel ROI verdicts (DOUBLE-DOWN / MAINTAIN / DEFUND / EXIT), a sensitivity-tested channel-mix recommendation, and the diminishing-returns inflection (e.g., 'which channel actually makes money — direct or partner?')." version: 2.8.0 author: claude-code-skills license: MIT @@ -79,6 +79,13 @@ Take the three reports into the quarterly channel review. The skill recommends; All scripts: stdlib only. `--help`, `--sample`, `--input`, `--output` work on all three. Industry tuning via `--profile {saas,api,enterprise-software,marketplace,hardware}` on the two analyzers. +## Quick example + +```bash +# Emits fully-loaded cost-to-serve per channel (direct vs partner-led) for the built-in sample channel data +cd commercial/skills/channel-economics && python3 scripts/cost_to_serve_calculator.py --sample +``` + ## References - `references/channel_economics_canon.md` — Skok, Bessemer State of the Cloud, Tunguz, Pacific Crest / KeyBanc SaaS Survey, Ramanujam, Jay McBain (Canalys) diff --git a/commercial/skills/partnerships-architect/SKILL.md b/commercial/skills/partnerships-architect/SKILL.md index 96fac356..a83b53ab 100644 --- a/commercial/skills/partnerships-architect/SKILL.md +++ b/commercial/skills/partnerships-architect/SKILL.md @@ -89,6 +89,13 @@ when triggered. All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a 5-tier partner classification with deterministic floors per tier for the built-in sample partner +cd commercial/skills/partnerships-architect && python3 scripts/partner_tier_classifier.py --sample +``` + ## References - `references/channel_partner_canon.md` — Caro on HP indirect channels, Chintagunta on channel economics, Hessling on partner programs, Forrester channel software stack, IDC channel research, Tien Tzuo subscription-channel models, Geoffrey Moore whole-product partnerships diff --git a/commercial/skills/pricing-strategist/SKILL.md b/commercial/skills/pricing-strategist/SKILL.md index 361ae722..6e02242e 100644 --- a/commercial/skills/pricing-strategist/SKILL.md +++ b/commercial/skills/pricing-strategist/SKILL.md @@ -67,6 +67,13 @@ Take model + range + packaging into the pricing committee. Skill does not commit All scripts: stdlib only. `--help` and `--sample` work on all three. +## Quick example + +```bash +# Emits a scored 5-model pricing-fit recommendation (subscription / usage / value / freemium / hybrid) for the built-in example +cd commercial/skills/pricing-strategist && python3 scripts/pricing_model_picker.py --sample +``` + ## References - `references/saas_pricing_canon.md` — Skok, Tunguz, Campbell, Ramanujam, BVP, Shevlin, Stanford GSB diff --git a/engineering-team/README.md b/engineering-team/README.md index aa7cc0be..d90247ec 100644 --- a/engineering-team/README.md +++ b/engineering-team/README.md @@ -1,6 +1,6 @@ # Engineering Skills Collection -Complete set of 18 engineering role skills tailored to your tech stack (ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python). +Complete set of 32 engineering skills (role skills, security suite, AI/ML/Data, and specialized tools) tailored to your tech stack (ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python). ## ⚡ Installation diff --git a/engineering-team/START_HERE.md b/engineering-team/START_HERE.md index 54995231..d5fd3ab4 100644 --- a/engineering-team/START_HERE.md +++ b/engineering-team/START_HERE.md @@ -2,7 +2,7 @@ ## 📦 **What You're Getting** -**14 world-class, senior-level skills** for building exceptional engineering and AI/ML/Data teams. +**32 production-ready skills** for building exceptional engineering and AI/ML/Data teams (this quick-start tour covers the original 14 role skills; see README.md for the full current list). All skills follow your exact template structure with: - ✅ **SKILL.md** - Complete documentation with quick start diff --git a/engineering-team/aws-solution-architect.zip b/engineering-team/aws-solution-architect.zip deleted file mode 100644 index 9071f14a..00000000 Binary files a/engineering-team/aws-solution-architect.zip and /dev/null differ diff --git a/engineering-team/ms365-tenant-manager.zip b/engineering-team/ms365-tenant-manager.zip deleted file mode 100644 index f3eed7cc..00000000 Binary files a/engineering-team/ms365-tenant-manager.zip and /dev/null differ diff --git a/engineering-team/self-improving-agent/skills/extract/SKILL.md b/engineering-team/self-improving-agent/skills/extract/SKILL.md index 7836857b..fad8cdd5 100644 --- a/engineering-team/self-improving-agent/skills/extract/SKILL.md +++ b/engineering-team/self-improving-agent/skills/extract/SKILL.md @@ -1,6 +1,6 @@ --- name: "extract" -description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples." +description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples. Use when the user runs /si:extract or asks to package a recurring solution from memory into a skill." --- # /si:extract — Create Skills from Patterns diff --git a/engineering-team/self-improving-agent/skills/promote/SKILL.md b/engineering-team/self-improving-agent/skills/promote/SKILL.md index cbade7ab..73010943 100644 --- a/engineering-team/self-improving-agent/skills/promote/SKILL.md +++ b/engineering-team/self-improving-agent/skills/promote/SKILL.md @@ -1,6 +1,6 @@ --- name: "promote" -description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement." +description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement. Use when the user runs /si:promote or asks to make a learned behavior permanent." --- # /si:promote — Graduate Learnings to Rules diff --git a/engineering-team/self-improving-agent/skills/review/SKILL.md b/engineering-team/self-improving-agent/skills/review/SKILL.md index c4c9566f..14c518be 100644 --- a/engineering-team/self-improving-agent/skills/review/SKILL.md +++ b/engineering-team/self-improving-agent/skills/review/SKILL.md @@ -1,6 +1,6 @@ --- name: "review" -description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics." +description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics. Use when the user runs /si:review or asks what has been learned and what should be promoted or pruned." --- # /si:review — Analyze Auto-Memory diff --git a/engineering-team/self-improving-agent/skills/status/SKILL.md b/engineering-team/self-improving-agent/skills/status/SKILL.md index 359a6de6..e8ae8fb0 100644 --- a/engineering-team/self-improving-agent/skills/status/SKILL.md +++ b/engineering-team/self-improving-agent/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations." +description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations. Use when the user runs /si:status or asks how full or healthy the agent memory is." --- # /si:status — Memory Health Dashboard diff --git a/engineering-team/skills/engineering-skills/SKILL.md b/engineering-team/skills/engineering-skills/SKILL.md index 47a4879a..4c0b1b25 100644 --- a/engineering-team/skills/engineering-skills/SKILL.md +++ b/engineering-team/skills/engineering-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "engineering-skills" -description: "23 engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365. 30+ Python tools (stdlib-only)." +description: "Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -20,7 +20,7 @@ agents: # Engineering Team Skills -23 production-ready engineering skills organized into core engineering, AI/ML/Data, and specialized tools. +32 production-ready engineering skills organized into core engineering, security, AI/ML/Data, and specialized tools. ## Quick Start @@ -86,6 +86,6 @@ No pip install needed. Scripts include embedded samples for demo mode. ## Rules -- Load only the specific skill SKILL.md you need — don't bulk-load all 23 +- Load only the specific skill SKILL.md you need — don't bulk-load all 32 - Use Python tools for analysis and scaffolding, not manual judgment - Check CLAUDE.md for tool usage examples and workflows diff --git a/engineering-team/skills/incident-commander/SKILL.md b/engineering-team/skills/incident-commander/SKILL.md index 77748a39..e58b58c7 100644 --- a/engineering-team/skills/incident-commander/SKILL.md +++ b/engineering-team/skills/incident-commander/SKILL.md @@ -13,7 +13,9 @@ description: "Comprehensive incident response framework from detection through r ## Overview -The Incident Commander skill provides a comprehensive incident response framework for managing technology incidents from detection through resolution and post-incident review. This skill implements battle-tested practices from SRE and DevOps teams at scale, providing structured tools for severity classification, timeline reconstruction, and thorough post-incident analysis. +Incident response framework for **availability/reliability incidents** (outages, degradations, failed deploys): severity classification, timeline reconstruction, and post-incident review. + +**This is NOT security incident triage.** For security events (ransomware, intrusion, data exfiltration, IOC analysis, NIST SP 800-61 forensics), route to `incident-response`. Both skills use SEV1-SEV4 labels; this one scores operational impact (users, revenue, SLA), while `incident-response` classifies attack types and forensic handling. ## Key Features @@ -467,10 +469,3 @@ python scripts/pir_generator.py --incident assets/sample_incident_pir_data.json - Deployment tracking systems - Feature flag platforms for quick rollbacks -## Conclusion - -The Incident Commander skill provides a comprehensive framework for managing incidents from detection through post-incident review. By implementing structured processes, clear communication templates, and thorough analysis tools, teams can improve their incident response capabilities and build more resilient systems. - -The key to successful incident management is preparation, practice, and continuous learning. Use this framework as a starting point, but adapt it to your organization's specific needs, culture, and technical environment. - -Remember: The goal isn't to prevent all incidents (which is impossible), but to detect them quickly, respond effectively, communicate clearly, and learn continuously. diff --git a/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py b/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py deleted file mode 100644 index ad49b5b7..00000000 --- a/engineering-team/skills/incident-commander/scripts/incident_timeline_builder.py +++ /dev/null @@ -1,742 +0,0 @@ -#!/usr/bin/env python3 -""" -Incident Timeline Builder - -Builds structured incident timelines with automatic phase detection, gap analysis, -communication template generation, and response metrics calculation. Produces -professional reports suitable for post-incident review and stakeholder briefing. - -Usage: - python incident_timeline_builder.py incident_data.json - python incident_timeline_builder.py incident_data.json --format json - python incident_timeline_builder.py incident_data.json --format markdown - cat incident_data.json | python incident_timeline_builder.py --format text -""" - -import argparse -import json -import sys -from datetime import datetime, timedelta -from typing import Any, Dict, List, Optional, Tuple - - -# --------------------------------------------------------------------------- -# Configuration Constants -# --------------------------------------------------------------------------- - -ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ" - -EVENT_TYPES = [ - "detection", "declaration", "escalation", "investigation", - "mitigation", "communication", "resolution", "action_item", -] - -SEVERITY_LEVELS = { - "SEV1": {"label": "Critical", "rank": 1}, - "SEV2": {"label": "Major", "rank": 2}, - "SEV3": {"label": "Minor", "rank": 3}, - "SEV4": {"label": "Low", "rank": 4}, -} - -PHASE_DEFINITIONS = [ - {"name": "Detection", "trigger_types": ["detection"], - "description": "Issue detected via monitoring, alerting, or user report."}, - {"name": "Triage", "trigger_types": ["declaration", "escalation"], - "description": "Incident declared, severity assessed, commander assigned."}, - {"name": "Investigation", "trigger_types": ["investigation"], - "description": "Root cause analysis and impact assessment underway."}, - {"name": "Mitigation", "trigger_types": ["mitigation"], - "description": "Active work to reduce or eliminate customer impact."}, - {"name": "Resolution", "trigger_types": ["resolution"], - "description": "Service restored to normal operating parameters."}, -] - -GAP_THRESHOLD_MINUTES = 15 - -DECISION_EVENT_TYPES = {"escalation", "mitigation", "declaration", "resolution"} - - -# --------------------------------------------------------------------------- -# Data Model Classes -# --------------------------------------------------------------------------- - -class IncidentEvent: - """Represents a single event in the incident timeline.""" - - def __init__(self, data: Dict[str, Any]): - self.timestamp_raw: str = data.get("timestamp", "") - self.timestamp: Optional[datetime] = _parse_timestamp(self.timestamp_raw) - self.type: str = data.get("type", "unknown").lower().strip() - self.actor: str = data.get("actor", "unknown") - self.description: str = data.get("description", "") - self.metadata: Dict[str, Any] = data.get("metadata", {}) - - def to_dict(self) -> Dict[str, Any]: - result: Dict[str, Any] = { - "timestamp": self.timestamp_raw, "type": self.type, - "actor": self.actor, "description": self.description, - } - if self.metadata: - result["metadata"] = self.metadata - return result - - @property - def is_decision_point(self) -> bool: - return self.type in DECISION_EVENT_TYPES - - -class IncidentPhase: - """Represents a detected phase of the incident lifecycle.""" - - def __init__(self, name: str, description: str): - self.name: str = name - self.description: str = description - self.start_time: Optional[datetime] = None - self.end_time: Optional[datetime] = None - self.events: List[IncidentEvent] = [] - - @property - def duration_minutes(self) -> Optional[float]: - if self.start_time and self.end_time: - return (self.end_time - self.start_time).total_seconds() / 60.0 - return None - - def to_dict(self) -> Dict[str, Any]: - dur = self.duration_minutes - return { - "name": self.name, "description": self.description, - "start_time": self.start_time.strftime(ISO_FORMAT) if self.start_time else None, - "end_time": self.end_time.strftime(ISO_FORMAT) if self.end_time else None, - "duration_minutes": round(dur, 1) if dur is not None else None, - "event_count": len(self.events), - } - - -class CommunicationTemplate: - """A generated communication message for a specific audience.""" - - def __init__(self, template_type: str, audience: str, subject: str, body: str): - self.template_type = template_type - self.audience = audience - self.subject = subject - self.body = body - - def to_dict(self) -> Dict[str, Any]: - return {"template_type": self.template_type, "audience": self.audience, - "subject": self.subject, "body": self.body} - - -class TimelineGap: - """Represents a gap in the timeline where no events were logged.""" - - def __init__(self, start: datetime, end: datetime, duration_minutes: float): - self.start = start - self.end = end - self.duration_minutes = duration_minutes - - def to_dict(self) -> Dict[str, Any]: - return {"start": self.start.strftime(ISO_FORMAT), - "end": self.end.strftime(ISO_FORMAT), - "duration_minutes": round(self.duration_minutes, 1)} - - -class TimelineAnalysis: - """Holds the complete analysis result for an incident timeline.""" - - def __init__(self): - self.incident_id: str = "" - self.incident_title: str = "" - self.severity: str = "" - self.status: str = "" - self.commander: str = "" - self.service: str = "" - self.affected_services: List[str] = [] - self.declared_at: Optional[datetime] = None - self.resolved_at: Optional[datetime] = None - self.events: List[IncidentEvent] = [] - self.phases: List[IncidentPhase] = [] - self.gaps: List[TimelineGap] = [] - self.decision_points: List[IncidentEvent] = [] - self.metrics: Dict[str, Any] = {} - self.communications: List[CommunicationTemplate] = [] - self.errors: List[str] = [] - - -# --------------------------------------------------------------------------- -# Timestamp Helpers -# --------------------------------------------------------------------------- - -def _parse_timestamp(raw: str) -> Optional[datetime]: - """Parse an ISO-8601 timestamp string into a datetime object.""" - if not raw: - return None - cleaned = raw.replace("Z", "+00:00") if raw.endswith("Z") else raw - try: - return datetime.fromisoformat(cleaned).replace(tzinfo=None) - except (ValueError, AttributeError): - pass - try: - return datetime.strptime(raw, ISO_FORMAT) - except ValueError: - return None - - -def _fmt_duration(minutes: Optional[float]) -> str: - """Format a duration in minutes as a human-readable string.""" - if minutes is None: - return "N/A" - if minutes < 1: - return f"{minutes * 60:.0f}s" - if minutes < 60: - return f"{minutes:.0f}m" - hours, remaining = int(minutes // 60), int(minutes % 60) - return f"{hours}h" if remaining == 0 else f"{hours}h {remaining}m" - - -def _fmt_ts(dt: Optional[datetime]) -> str: - """Format a datetime as HH:MM:SS for display.""" - return dt.strftime("%H:%M:%S") if dt else "??:??:??" - - -def _sev_label(sev: str) -> str: - """Return the human label for a severity code.""" - return SEVERITY_LEVELS.get(sev, {}).get("label", sev) - - -# --------------------------------------------------------------------------- -# Core Analysis Functions -# --------------------------------------------------------------------------- - -def parse_incident_data(data: Dict[str, Any]) -> TimelineAnalysis: - """Parse raw incident JSON into a TimelineAnalysis with populated fields.""" - a = TimelineAnalysis() - inc = data.get("incident", {}) - a.incident_id = inc.get("id", "UNKNOWN") - a.incident_title = inc.get("title", "Untitled Incident") - a.severity = inc.get("severity", "UNKNOWN").upper() - a.status = inc.get("status", "unknown").lower() - a.commander = inc.get("commander", "Unassigned") - a.service = inc.get("service", "unknown") - a.affected_services = inc.get("affected_services", []) - a.declared_at = _parse_timestamp(inc.get("declared_at", "")) - a.resolved_at = _parse_timestamp(inc.get("resolved_at", "")) - - raw_events = data.get("events", []) - if not raw_events: - a.errors.append("No events found in incident data.") - return a - - for raw in raw_events: - event = IncidentEvent(raw) - if event.timestamp is None: - a.errors.append(f"Skipping event with unparseable timestamp: {raw.get('timestamp', '')}") - continue - a.events.append(event) - - a.events.sort(key=lambda e: e.timestamp) # type: ignore[arg-type] - return a - - -def detect_phases(analysis: TimelineAnalysis) -> None: - """Detect incident lifecycle phases from the ordered event stream.""" - if not analysis.events: - return - - trigger_map: Dict[str, Dict[str, str]] = {} - for pdef in PHASE_DEFINITIONS: - for ttype in pdef["trigger_types"]: - trigger_map[ttype] = {"name": pdef["name"], "description": pdef["description"]} - - phase_by_name: Dict[str, IncidentPhase] = {} - phase_order: List[str] = [] - current: Optional[IncidentPhase] = None - - for event in analysis.events: - pinfo = trigger_map.get(event.type) - if pinfo and pinfo["name"] not in phase_by_name: - if current is not None: - current.end_time = event.timestamp - phase = IncidentPhase(pinfo["name"], pinfo["description"]) - phase.start_time = event.timestamp - phase_by_name[pinfo["name"]] = phase - phase_order.append(pinfo["name"]) - current = phase - if current is not None: - current.events.append(event) - - if current is not None: - current.end_time = analysis.resolved_at or analysis.events[-1].timestamp - - analysis.phases = [phase_by_name[n] for n in phase_order] - - -def detect_gaps(analysis: TimelineAnalysis) -> None: - """Identify gaps longer than GAP_THRESHOLD_MINUTES between consecutive events.""" - for i in range(len(analysis.events) - 1): - ts_a, ts_b = analysis.events[i].timestamp, analysis.events[i + 1].timestamp - if ts_a is None or ts_b is None: - continue - delta = (ts_b - ts_a).total_seconds() / 60.0 - if delta >= GAP_THRESHOLD_MINUTES: - analysis.gaps.append(TimelineGap(start=ts_a, end=ts_b, duration_minutes=delta)) - - -def identify_decision_points(analysis: TimelineAnalysis) -> None: - """Extract key decision-point events from the timeline.""" - analysis.decision_points = [e for e in analysis.events if e.is_decision_point] - - -def calculate_metrics(analysis: TimelineAnalysis) -> None: - """Calculate incident response metrics: MTTD, MTTR, phase durations.""" - m: Dict[str, Any] = {} - det = [e for e in analysis.events if e.type == "detection"] - first_det = det[0].timestamp if det else None - first_ts = analysis.events[0].timestamp if analysis.events else None - - # MTTD: first event to first detection. - if first_ts and first_det: - m["mttd_minutes"] = round((first_det - first_ts).total_seconds() / 60.0, 1) - else: - m["mttd_minutes"] = None - - # MTTR: detection to resolution. - if first_det and analysis.resolved_at: - m["mttr_minutes"] = round((analysis.resolved_at - first_det).total_seconds() / 60.0, 1) - else: - m["mttr_minutes"] = None - - # Total duration. - if analysis.declared_at and analysis.resolved_at: - m["total_duration_minutes"] = round( - (analysis.resolved_at - analysis.declared_at).total_seconds() / 60.0, 1) - else: - m["total_duration_minutes"] = None - - # Phase durations. - m["phase_durations"] = { - p.name: (round(p.duration_minutes, 1) if p.duration_minutes is not None else None) - for p in analysis.phases - } - - # Event counts by type. - tc: Dict[str, int] = {} - for e in analysis.events: - tc[e.type] = tc.get(e.type, 0) + 1 - m["event_counts_by_type"] = tc - - # Gap statistics. - m["gap_count"] = len(analysis.gaps) - if analysis.gaps: - gm = [g.duration_minutes for g in analysis.gaps] - m["longest_gap_minutes"] = round(max(gm), 1) - m["total_gap_minutes"] = round(sum(gm), 1) - else: - m["longest_gap_minutes"] = 0 - m["total_gap_minutes"] = 0 - - m["total_events"] = len(analysis.events) - m["decision_point_count"] = len(analysis.decision_points) - m["phase_count"] = len(analysis.phases) - analysis.metrics = m - - -# --------------------------------------------------------------------------- -# Communication Template Generation -# --------------------------------------------------------------------------- - -def generate_communications(analysis: TimelineAnalysis) -> None: - """Generate four communication templates based on incident data.""" - sev, sl = analysis.severity, _sev_label(analysis.severity) - title, svc = analysis.incident_title, analysis.service - affected = ", ".join(analysis.affected_services) or "none identified" - cmd, iid = analysis.commander, analysis.incident_id - decl = analysis.declared_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.declared_at else "TBD" - resv = analysis.resolved_at.strftime("%Y-%m-%d %H:%M UTC") if analysis.resolved_at else "TBD" - dur = _fmt_duration(analysis.metrics.get("total_duration_minutes")) - resolved = analysis.status == "resolved" - - # 1 -- Initial stakeholder notification - analysis.communications.append(CommunicationTemplate( - "initial_notification", "internal", f"[{sev}] Incident Declared: {title}", - f"An incident has been declared for {svc}.\n\n" - f"Incident ID: {iid}\nSeverity: {sev} ({sl})\nCommander: {cmd}\n" - f"Declared at: {decl}\nAffected services: {affected}\n\n" - f"The incident team is actively investigating. Updates will follow.", - )) - - # 2 -- Status page update - if resolved: - sp_subj = f"[Resolved] {title}" - sp_body = (f"The incident affecting {svc} has been resolved.\n\n" - f"Duration: {dur}\nAll affected services ({affected}) are restored. " - f"A post-incident review will be published within 48 hours.") - else: - sp_subj = f"[Investigating] {title}" - sp_body = (f"We are investigating degraded performance in {svc}. " - f"Affected services: {affected}.\n\n" - f"Our team is working to identify the root cause. Updates every 30 minutes.") - analysis.communications.append(CommunicationTemplate( - "status_page", "external", sp_subj, sp_body)) - - # 3 -- Executive summary - phase_lines = "\n".join( - f" - {p.name}: {_fmt_duration(p.duration_minutes)}" for p in analysis.phases - ) or " No phase data available." - mttd = _fmt_duration(analysis.metrics.get("mttd_minutes")) - mttr = _fmt_duration(analysis.metrics.get("mttr_minutes")) - analysis.communications.append(CommunicationTemplate( - "executive_summary", "executive", f"Executive Summary: {iid} - {title}", - f"Incident: {iid} - {title}\nSeverity: {sev} ({sl})\n" - f"Service: {svc}\nCommander: {cmd}\nStatus: {analysis.status.capitalize()}\n" - f"Declared: {decl}\nResolved: {resv}\nDuration: {dur}\n\n" - f"Key Metrics:\n - MTTD: {mttd}\n - MTTR: {mttr}\n" - f" - Timeline Gaps: {analysis.metrics.get('gap_count', 0)}\n\n" - f"Phase Breakdown:\n{phase_lines}\n\nAffected Services: {affected}", - )) - - # 4 -- Customer notification - if resolved: - cust_body = (f"We experienced an issue affecting {svc} starting at {decl}.\n\n" - f"The issue was resolved at {resv} (duration: {dur}). " - f"We apologize for any inconvenience and are reviewing to prevent recurrence.") - else: - cust_body = (f"We are experiencing an issue affecting {svc} starting at {decl}.\n\n" - f"Our engineering team is actively working to resolve this. " - f"We will provide updates as the situation develops. We apologize for the inconvenience.") - analysis.communications.append(CommunicationTemplate( - "customer_notification", "external", f"Service Update: {title}", cust_body)) - - -# --------------------------------------------------------------------------- -# Main Analysis Orchestrator -# --------------------------------------------------------------------------- - -def build_timeline(data: Dict[str, Any]) -> TimelineAnalysis: - """Run the full timeline analysis pipeline on raw incident data.""" - analysis = parse_incident_data(data) - if analysis.errors and not analysis.events: - return analysis - detect_phases(analysis) - detect_gaps(analysis) - identify_decision_points(analysis) - calculate_metrics(analysis) - generate_communications(analysis) - return analysis - - -# --------------------------------------------------------------------------- -# Output Formatters -# --------------------------------------------------------------------------- - -def format_text_output(analysis: TimelineAnalysis) -> str: - """Format the analysis as a human-readable text report.""" - L: List[str] = [] - w = 64 - - L.append("=" * w) - L.append("INCIDENT TIMELINE REPORT") - L.append("=" * w) - L.append("") - - if analysis.errors: - for err in analysis.errors: - L.append(f" WARNING: {err}") - L.append("") - if not analysis.events: - return "\n".join(L) - - # Summary - L.append("INCIDENT SUMMARY") - L.append("-" * 32) - L.append(f" ID: {analysis.incident_id}") - L.append(f" Title: {analysis.incident_title}") - L.append(f" Severity: {analysis.severity}") - L.append(f" Status: {analysis.status.capitalize()}") - L.append(f" Commander: {analysis.commander}") - L.append(f" Service: {analysis.service}") - if analysis.affected_services: - L.append(f" Affected: {', '.join(analysis.affected_services)}") - L.append(f" Duration: {_fmt_duration(analysis.metrics.get('total_duration_minutes'))}") - L.append("") - - # Key metrics - L.append("KEY METRICS") - L.append("-" * 32) - L.append(f" MTTD (Mean Time to Detect): {_fmt_duration(analysis.metrics.get('mttd_minutes'))}") - L.append(f" MTTR (Mean Time to Resolve): {_fmt_duration(analysis.metrics.get('mttr_minutes'))}") - L.append(f" Total Events: {analysis.metrics.get('total_events', 0)}") - L.append(f" Decision Points: {analysis.metrics.get('decision_point_count', 0)}") - L.append(f" Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m): {analysis.metrics.get('gap_count', 0)}") - L.append("") - - # Phases - L.append("INCIDENT PHASES") - L.append("-" * 32) - if analysis.phases: - for p in analysis.phases: - L.append(f" [{_fmt_ts(p.start_time)} - {_fmt_ts(p.end_time)}] {p.name} ({_fmt_duration(p.duration_minutes)})") - L.append(f" {p.description}") - L.append(f" Events: {len(p.events)}") - else: - L.append(" No phases detected.") - L.append("") - - # Chronological timeline - L.append("CHRONOLOGICAL TIMELINE") - L.append("-" * 32) - for e in analysis.events: - marker = "*" if e.is_decision_point else " " - L.append(f" {_fmt_ts(e.timestamp)} {marker} [{e.type.upper():13s}] {e.actor}") - L.append(f" {e.description}") - L.append("") - L.append(" (* = key decision point)") - L.append("") - - # Gap warnings - if analysis.gaps: - L.append("GAP ANALYSIS") - L.append("-" * 32) - for g in analysis.gaps: - L.append(f" WARNING: {_fmt_duration(g.duration_minutes)} gap between {_fmt_ts(g.start)} and {_fmt_ts(g.end)}") - L.append("") - - # Decision points - if analysis.decision_points: - L.append("KEY DECISION POINTS") - L.append("-" * 32) - for dp in analysis.decision_points: - L.append(f" {_fmt_ts(dp.timestamp)} [{dp.type.upper()}] {dp.description}") - L.append("") - - # Communications - if analysis.communications: - L.append("GENERATED COMMUNICATIONS") - L.append("-" * 32) - for c in analysis.communications: - L.append(f" Type: {c.template_type}") - L.append(f" Audience: {c.audience}") - L.append(f" Subject: {c.subject}") - L.append(" ---") - for bl in c.body.split("\n"): - L.append(f" {bl}") - L.append("") - - L.append("=" * w) - L.append("END OF REPORT") - L.append("=" * w) - return "\n".join(L) - - -def format_json_output(analysis: TimelineAnalysis) -> Dict[str, Any]: - """Format the analysis as a structured JSON-serializable dictionary.""" - return { - "incident": { - "id": analysis.incident_id, "title": analysis.incident_title, - "severity": analysis.severity, "status": analysis.status, - "commander": analysis.commander, "service": analysis.service, - "affected_services": analysis.affected_services, - "declared_at": analysis.declared_at.strftime(ISO_FORMAT) if analysis.declared_at else None, - "resolved_at": analysis.resolved_at.strftime(ISO_FORMAT) if analysis.resolved_at else None, - }, - "timeline": [e.to_dict() for e in analysis.events], - "phases": [p.to_dict() for p in analysis.phases], - "gaps": [g.to_dict() for g in analysis.gaps], - "decision_points": [e.to_dict() for e in analysis.decision_points], - "metrics": analysis.metrics, - "communications": [c.to_dict() for c in analysis.communications], - "errors": analysis.errors if analysis.errors else [], - } - - -def format_markdown_output(analysis: TimelineAnalysis) -> str: - """Format the analysis as a professional Markdown report.""" - L: List[str] = [] - - L.append(f"# Incident Timeline Report: {analysis.incident_id}") - L.append("") - - if analysis.errors: - L.append("> **Warnings:**") - for err in analysis.errors: - L.append(f"> - {err}") - L.append("") - if not analysis.events: - return "\n".join(L) - - # Summary table - L.append("## Incident Summary") - L.append("") - L.append("| Field | Value |") - L.append("|-------|-------|") - L.append(f"| **ID** | {analysis.incident_id} |") - L.append(f"| **Title** | {analysis.incident_title} |") - L.append(f"| **Severity** | {analysis.severity} ({_sev_label(analysis.severity)}) |") - L.append(f"| **Status** | {analysis.status.capitalize()} |") - L.append(f"| **Commander** | {analysis.commander} |") - L.append(f"| **Service** | {analysis.service} |") - if analysis.affected_services: - L.append(f"| **Affected Services** | {', '.join(analysis.affected_services)} |") - L.append(f"| **Duration** | {_fmt_duration(analysis.metrics.get('total_duration_minutes'))} |") - L.append("") - - # Key metrics - L.append("## Key Metrics") - L.append("") - L.append(f"- **MTTD (Mean Time to Detect):** {_fmt_duration(analysis.metrics.get('mttd_minutes'))}") - L.append(f"- **MTTR (Mean Time to Resolve):** {_fmt_duration(analysis.metrics.get('mttr_minutes'))}") - L.append(f"- **Total Events:** {analysis.metrics.get('total_events', 0)}") - L.append(f"- **Decision Points:** {analysis.metrics.get('decision_point_count', 0)}") - L.append(f"- **Timeline Gaps (>{GAP_THRESHOLD_MINUTES}m):** {analysis.metrics.get('gap_count', 0)}") - if analysis.metrics.get("longest_gap_minutes", 0) > 0: - L.append(f"- **Longest Gap:** {_fmt_duration(analysis.metrics.get('longest_gap_minutes'))}") - L.append("") - - # Phases table - L.append("## Incident Phases") - L.append("") - if analysis.phases: - L.append("| Phase | Start | End | Duration | Events |") - L.append("|-------|-------|-----|----------|--------|") - for p in analysis.phases: - L.append(f"| {p.name} | {_fmt_ts(p.start_time)} | {_fmt_ts(p.end_time)} | {_fmt_duration(p.duration_minutes)} | {len(p.events)} |") - L.append("") - # ASCII bar chart - max_dur = max((p.duration_minutes for p in analysis.phases if p.duration_minutes), default=0) - if max_dur and max_dur > 0: - L.append("### Phase Duration Distribution") - L.append("") - L.append("```") - for p in analysis.phases: - d = p.duration_minutes or 0 - bar = "#" * int((d / max_dur) * 40) - L.append(f" {p.name:15s} |{bar} {_fmt_duration(d)}") - L.append("```") - L.append("") - else: - L.append("No phases detected.") - L.append("") - - # Chronological timeline - L.append("## Chronological Timeline") - L.append("") - for e in analysis.events: - dm = " **[KEY DECISION]**" if e.is_decision_point else "" - L.append(f"- `{_fmt_ts(e.timestamp)}` **{e.type.upper()}** ({e.actor}){dm}") - L.append(f" - {e.description}") - L.append("") - - # Gap analysis - if analysis.gaps: - L.append("## Gap Analysis") - L.append("") - L.append(f"> {len(analysis.gaps)} gap(s) of >{GAP_THRESHOLD_MINUTES} minutes detected. " - f"These may represent blind spots where important activity was not recorded.") - L.append("") - for g in analysis.gaps: - L.append(f"- **{_fmt_duration(g.duration_minutes)}** gap from `{_fmt_ts(g.start)}` to `{_fmt_ts(g.end)}`") - L.append("") - - # Decision points - if analysis.decision_points: - L.append("## Key Decision Points") - L.append("") - for dp in analysis.decision_points: - L.append(f"1. `{_fmt_ts(dp.timestamp)}` **{dp.type.upper()}** - {dp.description}") - L.append("") - - # Communications - if analysis.communications: - L.append("## Generated Communications") - L.append("") - for c in analysis.communications: - L.append(f"### {c.template_type.replace('_', ' ').title()} ({c.audience})") - L.append("") - L.append(f"**Subject:** {c.subject}") - L.append("") - for bl in c.body.split("\n"): - L.append(bl) - L.append("") - L.append("---") - L.append("") - - # Event type breakdown - tc = analysis.metrics.get("event_counts_by_type", {}) - if tc: - L.append("## Event Type Breakdown") - L.append("") - L.append("| Type | Count |") - L.append("|------|-------|") - for etype, count in sorted(tc.items(), key=lambda x: -x[1]): - L.append(f"| {etype} | {count} |") - L.append("") - - L.append("---") - L.append(f"*Report generated for incident {analysis.incident_id}. All timestamps in UTC.*") - return "\n".join(L) - - -# --------------------------------------------------------------------------- -# CLI Interface -# --------------------------------------------------------------------------- - -def main() -> int: - """Main CLI entry point.""" - parser = argparse.ArgumentParser( - description="Build structured incident timelines with phase detection and communication templates." - ) - parser.add_argument( - "data_file", nargs="?", default=None, - help="JSON file with incident data (reads stdin if omitted)", - ) - parser.add_argument( - "--format", choices=["text", "json", "markdown"], default="text", - help="Output format (default: text)", - ) - args = parser.parse_args() - - try: - if args.data_file: - try: - with open(args.data_file, "r") as f: - raw_data = json.load(f) - except FileNotFoundError: - print(f"Error: File '{args.data_file}' not found.", file=sys.stderr) - return 1 - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON in '{args.data_file}': {e}", file=sys.stderr) - return 1 - else: - if sys.stdin.isatty(): - print("Error: No input file specified and stdin is a terminal. " - "Provide a file argument or pipe JSON to stdin.", file=sys.stderr) - return 1 - try: - raw_data = json.load(sys.stdin) - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON on stdin: {e}", file=sys.stderr) - return 1 - - if not isinstance(raw_data, dict): - print("Error: Input must be a JSON object.", file=sys.stderr) - return 1 - if "incident" not in raw_data and "events" not in raw_data: - print("Error: Input must contain at least 'incident' or 'events' keys.", file=sys.stderr) - return 1 - - analysis = build_timeline(raw_data) - - if args.format == "json": - print(json.dumps(format_json_output(analysis), indent=2)) - elif args.format == "markdown": - print(format_markdown_output(analysis)) - else: - print(format_text_output(analysis)) - return 0 - - except Exception as e: - print(f"Error: {e}", file=sys.stderr) - return 1 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/engineering-team/skills/incident-commander/scripts/postmortem_generator.py b/engineering-team/skills/incident-commander/scripts/postmortem_generator.py deleted file mode 100644 index 868f425f..00000000 --- a/engineering-team/skills/incident-commander/scripts/postmortem_generator.py +++ /dev/null @@ -1,804 +0,0 @@ -#!/usr/bin/env python3 -""" -Postmortem Generator - Generate structured postmortem reports with 5-Whys analysis. - -Produces comprehensive incident postmortem documents from structured JSON input, -including root cause analysis, contributing factor classification, action item -validation, MTTD/MTTR metrics, and customer impact summaries. - -Usage: - python postmortem_generator.py incident_data.json - python postmortem_generator.py incident_data.json --format markdown - python postmortem_generator.py incident_data.json --format json - cat incident_data.json | python postmortem_generator.py - -Input: - JSON object with keys: incident, timeline, resolution, action_items, participants. - See SKILL.md for the full input schema. -""" - -import argparse -import json -import sys -from datetime import datetime, timezone -from typing import Any, Dict, List, Optional, Tuple - - -# ---------- Constants and Configuration ---------- - -VERSION = "1.0.0" -SEVERITY_ORDER = {"SEV0": 0, "SEV1": 1, "SEV2": 2, "SEV3": 3, "SEV4": 4} -FACTOR_CATEGORIES = ("process", "tooling", "human", "environment", "external") -ACTION_TYPES = ("detection", "prevention", "mitigation", "process") -PRIORITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3, "P4": 4} -POSTMORTEM_TARGET_HOURS = 72 - -# Industry benchmarks for incident response (minutes, except postmortem) -BENCHMARKS = { - "SEV0": {"mttd": 5, "mttr": 60, "mitigate": 30, "declare": 5}, - "SEV1": {"mttd": 10, "mttr": 120, "mitigate": 60, "declare": 10}, - "SEV2": {"mttd": 30, "mttr": 480, "mitigate": 120, "declare": 30}, - "SEV3": {"mttd": 60, "mttr": 1440, "mitigate": 240, "declare": 60}, - "SEV4": {"mttd": 120, "mttr": 2880, "mitigate": 480, "declare": 120}, -} - -CAT_TO_ACTION = {"process": "process", "tooling": "detection", "human": "prevention", - "environment": "mitigation", "external": "prevention"} -CAT_WEIGHT = {"process": 1.0, "tooling": 0.9, "human": 0.8, "environment": 0.7, "external": 0.6} - -# Keywords used to classify contributing factors into categories -FACTOR_KEYWORDS = { - "process": ["process", "procedure", "workflow", "review", "approval", "checklist", - "runbook", "documentation", "policy", "standard", "protocol", "canary", - "deployment", "rollback", "change management"], - "tooling": ["tool", "monitor", "alert", "threshold", "automation", "test", "pipeline", - "ci/cd", "observability", "dashboard", "logging", "infrastructure", - "configuration", "config"], - "human": ["training", "knowledge", "experience", "communication", "handoff", "fatigue", - "oversight", "mistake", "error", "misunderstand", "assumption", "awareness"], - "environment": ["load", "traffic", "scale", "capacity", "resource", "network", "hardware", - "region", "latency", "timeout", "connection", "performance", "spike"], - "external": ["vendor", "third-party", "upstream", "downstream", "provider", "api", - "dependency", "partner", "dns", "cdn", "certificate"], -} - -# 5-Whys templates per category (each list is 5 why->answer steps) -WHY_TEMPLATES = { - "process": [ - "Why did this process gap exist? -> The existing process did not account for this scenario.", - "Why was the scenario not accounted for? -> It was not identified during the last process review.", - "Why was the process review incomplete? -> Reviews focus on known failure modes, not emerging risks.", - "Why are emerging risks not surfaced? -> No systematic mechanism to capture lessons from near-misses.", - "Why is there no near-miss capture mechanism? -> Incident learning is ad-hoc rather than systematic."], - "tooling": [ - "Why did the tooling fail to catch this? -> The relevant metric was not monitored or the threshold was misconfigured.", - "Why was the threshold misconfigured? -> It was set during initial deployment and never revisited.", - "Why was it never revisited? -> There is no scheduled review of monitoring configurations.", - "Why is there no scheduled review? -> Monitoring ownership is diffuse across teams.", - "Why is ownership diffuse? -> No clear operational runbook assigns monitoring review responsibilities."], - "human": [ - "Why did the human factor contribute? -> The individual lacked context needed to prevent the issue.", - "Why was context lacking? -> Knowledge was siloed and not documented accessibly.", - "Why was knowledge siloed? -> No structured onboarding or knowledge-sharing process for this area.", - "Why is there no knowledge-sharing process? -> Team capacity has been focused on feature delivery.", - "Why is capacity skewed toward features? -> Operational excellence is not weighted equally in planning."], - "environment": [ - "Why did the environment cause this failure? -> System capacity was insufficient for the load pattern.", - "Why was capacity insufficient? -> Load projections did not account for this traffic pattern.", - "Why were projections inaccurate? -> Load testing does not replicate production-scale variability.", - "Why doesn't load testing replicate production? -> Test environments lack realistic traffic generators.", - "Why are traffic generators missing? -> Investment in production-like test infrastructure was deferred."], - "external": [ - "Why did the external factor cause an incident? -> The system had a hard dependency with no fallback.", - "Why was there no fallback? -> The integration was assumed to be highly available.", - "Why was high availability assumed? -> SLA review of the external dependency was not performed.", - "Why was SLA review skipped? -> No standard checklist for evaluating third-party dependencies.", - "Why is there no evaluation checklist? -> Vendor management practices are informal and undocumented."], -} - -THEME_RECS = { - "process": ["Establish a quarterly process review cadence covering change management and deployment procedures.", - "Implement a near-miss tracking system to surface latent risks before they become incidents.", - "Create pre-deployment checklists that require sign-off from the service owner."], - "tooling": ["Schedule quarterly reviews of alerting thresholds and monitoring coverage.", - "Assign explicit monitoring ownership per service in operational runbooks.", - "Invest in synthetic monitoring and canary analysis for critical paths."], - "human": ["Build structured onboarding that covers incident-prone areas and past postmortems.", - "Implement blameless knowledge-sharing sessions after each incident.", - "Balance operational excellence work alongside feature delivery in sprint planning."], - "environment": ["Conduct periodic capacity planning reviews using production traffic replays.", - "Invest in production-like load-testing infrastructure with realistic traffic profiles.", - "Implement auto-scaling policies with validated upper-bound thresholds."], - "external": ["Perform formal SLA reviews for all third-party dependencies annually.", - "Implement circuit breakers and fallbacks for external service integrations.", - "Maintain a dependency registry with risk ratings and contingency plans."], -} - -MISSING_ACTION_TEMPLATES = { - "process": "Create or update runbook/checklist to prevent recurrence of this process gap", - "detection": "Add monitoring and alerting to detect this class of issue earlier", - "mitigation": "Implement auto-scaling or circuit-breaker to reduce blast radius", - "prevention": "Add automated safeguards (canary deploy, load test gate) to prevent recurrence", -} - - -# ---------- Data Model Classes ---------- - -class IncidentData: - """Parsed incident metadata.""" - def __init__(self, data: Dict[str, Any]) -> None: - self.id: str = data.get("id", "UNKNOWN") - self.title: str = data.get("title", "Untitled Incident") - self.severity: str = data.get("severity", "SEV3").upper() - self.commander: str = data.get("commander", "Unassigned") - self.service: str = data.get("service", "unknown-service") - self.affected_services: List[str] = data.get("affected_services", []) - - def to_dict(self) -> Dict[str, Any]: - return {"id": self.id, "title": self.title, "severity": self.severity, - "commander": self.commander, "service": self.service, - "affected_services": self.affected_services} - - -class TimelineMetrics: - """MTTD, MTTR, and other timing metrics computed from raw timestamps.""" - def __init__(self, timeline: Dict[str, str], severity: str) -> None: - self.severity = severity - self.issue_started = self._parse(timeline.get("issue_started")) - self.detected_at = self._parse(timeline.get("detected_at")) - self.declared_at = self._parse(timeline.get("declared_at")) - self.mitigated_at = self._parse(timeline.get("mitigated_at")) - self.resolved_at = self._parse(timeline.get("resolved_at")) - self.postmortem_at = self._parse(timeline.get("postmortem_at")) - - @staticmethod - def _parse(ts: Optional[str]) -> Optional[datetime]: - if ts is None: - return None - for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S"): - try: - dt = datetime.strptime(ts, fmt) - return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc) - except ValueError: - continue - return None - - def _delta_min(self, start: Optional[datetime], end: Optional[datetime]) -> Optional[float]: - if start is None or end is None: - return None - return round((end - start).total_seconds() / 60.0, 1) - - @property - def mttd(self) -> Optional[float]: - return self._delta_min(self.issue_started, self.detected_at) - - @property - def mttr(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.resolved_at) - - @property - def time_to_mitigate(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.mitigated_at) - - @property - def time_to_declare(self) -> Optional[float]: - return self._delta_min(self.detected_at, self.declared_at) - - @property - def postmortem_timeliness_hours(self) -> Optional[float]: - m = self._delta_min(self.resolved_at, self.postmortem_at) - return round(m / 60.0, 1) if m is not None else None - - @property - def postmortem_on_time(self) -> Optional[bool]: - h = self.postmortem_timeliness_hours - return h <= POSTMORTEM_TARGET_HOURS if h is not None else None - - def benchmark_comparison(self) -> Dict[str, Dict[str, Any]]: - bench = BENCHMARKS.get(self.severity, BENCHMARKS["SEV3"]) - results: Dict[str, Dict[str, Any]] = {} - for name, actual, target in [("mttd", self.mttd, bench["mttd"]), - ("mttr", self.mttr, bench["mttr"]), - ("time_to_mitigate", self.time_to_mitigate, bench["mitigate"]), - ("time_to_declare", self.time_to_declare, bench["declare"])]: - if actual is not None: - results[name] = {"actual_minutes": actual, "benchmark_minutes": target, - "met_benchmark": actual <= target, - "delta_minutes": round(actual - target, 1)} - h = self.postmortem_timeliness_hours - if h is not None: - results["postmortem_timeliness"] = { - "actual_hours": h, "target_hours": POSTMORTEM_TARGET_HOURS, - "met_target": self.postmortem_on_time, "delta_hours": round(h - POSTMORTEM_TARGET_HOURS, 1)} - return results - - def to_dict(self) -> Dict[str, Any]: - return {"mttd_minutes": self.mttd, "mttr_minutes": self.mttr, - "time_to_mitigate_minutes": self.time_to_mitigate, - "time_to_declare_minutes": self.time_to_declare, - "postmortem_timeliness_hours": self.postmortem_timeliness_hours, - "postmortem_on_time": self.postmortem_on_time, - "benchmarks": self.benchmark_comparison()} - - -class ContributingFactor: - """A classified contributing factor with weight and action-type mapping.""" - def __init__(self, description: str, index: int) -> None: - self.description = description - self.index = index - self.category = self._classify() - self.weight = round(max(1.0 - index * 0.15, 0.3) * CAT_WEIGHT.get(self.category, 0.8), 2) - self.mapped_action_type = CAT_TO_ACTION.get(self.category, "process") - - def _classify(self) -> str: - lower = self.description.lower() - scores = {cat: sum(1 for kw in kws if kw in lower) for cat, kws in FACTOR_KEYWORDS.items()} - best = max(scores, key=lambda k: scores[k]) - return best if scores[best] > 0 else "process" - - def to_dict(self) -> Dict[str, Any]: - return {"description": self.description, "category": self.category, - "weight": self.weight, "mapped_action_type": self.mapped_action_type} - - -class FiveWhysAnalysis: - """Structured 5-Whys chain for a contributing factor.""" - def __init__(self, factor: ContributingFactor) -> None: - self.factor = factor - self.systemic_theme: str = factor.category - self.chain: List[str] = [f"Why? {factor.description}"] + \ - WHY_TEMPLATES.get(factor.category, WHY_TEMPLATES["process"]) - - def to_dict(self) -> Dict[str, Any]: - return {"factor": self.factor.description, "category": self.factor.category, - "chain": self.chain, "systemic_theme": self.systemic_theme} - - -class ActionItem: - """Parsed and validated action item.""" - def __init__(self, data: Dict[str, Any]) -> None: - self.title: str = data.get("title", "") - self.owner: str = data.get("owner", "") - self.priority: str = data.get("priority", "P3") - self.deadline: str = data.get("deadline", "") - self.type: str = data.get("type", "process") - self.status: str = data.get("status", "open") - self.validation_issues: List[str] = [] - self.quality_score: int = 0 - self._validate() - - def _validate(self) -> None: - self.validation_issues = [] - if not self.title: - self.validation_issues.append("Missing title") - if not self.owner: - self.validation_issues.append("Missing owner") - if not self.deadline: - self.validation_issues.append("Missing deadline") - if self.priority not in PRIORITY_ORDER: - self.validation_issues.append(f"Invalid priority: {self.priority}") - if self.type not in ACTION_TYPES: - self.validation_issues.append(f"Invalid type: {self.type}") - self.quality_score = self._score_quality() - - def _score_quality(self) -> int: - """Score 0-100: specific, measurable, achievable.""" - s = 0 - if len(self.title) > 10: s += 20 - if self.owner: s += 20 - if self.deadline: s += 20 - if self.priority in PRIORITY_ORDER: s += 10 - if self.type in ACTION_TYPES: s += 10 - if any(kw in self.title.lower() for kw in ["%", "threshold", "within", "before", - "after", "less than", "greater than"]): - s += 10 - if len(self.title.split()) >= 5: s += 10 - return min(s, 100) - - @property - def is_valid(self) -> bool: - return len(self.validation_issues) == 0 - - @property - def is_past_deadline(self) -> bool: - if not self.deadline or self.status != "open": - return False - try: - dl = datetime.strptime(self.deadline, "%Y-%m-%d").replace(tzinfo=timezone.utc) - return datetime.now(timezone.utc) > dl - except ValueError: - return False - - def to_dict(self) -> Dict[str, Any]: - return {"title": self.title, "owner": self.owner, "priority": self.priority, - "deadline": self.deadline, "type": self.type, "status": self.status, - "is_valid": self.is_valid, "validation_issues": self.validation_issues, - "quality_score": self.quality_score, "is_past_deadline": self.is_past_deadline} - - -class PostmortemReport: - """Complete postmortem document assembled from all analysis components.""" - - def __init__(self, raw: Dict[str, Any]) -> None: - self.raw = raw - self.incident = IncidentData(raw.get("incident", {})) - self.timeline = TimelineMetrics(raw.get("timeline", {}), self.incident.severity) - self.resolution: Dict[str, Any] = raw.get("resolution", {}) - self.participants: List[Dict[str, str]] = raw.get("participants", []) - # Derived analysis - self.contributing_factors = [ContributingFactor(f, i) - for i, f in enumerate(self.resolution.get("contributing_factors", []))] - self.five_whys = [FiveWhysAnalysis(f) for f in self.contributing_factors] - self.action_items = [ActionItem(a) for a in raw.get("action_items", [])] - self.factor_distribution = self._compute_factor_distribution() - self.coverage_gaps = self._find_coverage_gaps() - self.suggested_actions = self._suggest_missing_actions() - self.theme_recommendations = self._build_theme_recommendations() - - def _compute_factor_distribution(self) -> Dict[str, float]: - dist: Dict[str, float] = {c: 0.0 for c in FACTOR_CATEGORIES} - total = sum(f.weight for f in self.contributing_factors) or 1.0 - for f in self.contributing_factors: - dist[f.category] += f.weight - return {k: round(v / total * 100, 1) for k, v in dist.items()} - - def _find_coverage_gaps(self) -> List[str]: - factor_cats = {f.category for f in self.contributing_factors} - action_types = {a.type for a in self.action_items} - gaps = [] - for cat in factor_cats: - expected = CAT_TO_ACTION.get(cat) - if expected and expected not in action_types: - gaps.append(f"No '{expected}' action item to address '{cat}' contributing factor") - return gaps - - def _suggest_missing_actions(self) -> List[Dict[str, str]]: - factor_cats = {f.category for f in self.contributing_factors} - action_types = {a.type for a in self.action_items} - suggestions = [] - for cat in factor_cats: - expected = CAT_TO_ACTION.get(cat) - if expected and expected not in action_types: - suggestions.append({ - "type": expected, - "suggestion": MISSING_ACTION_TEMPLATES.get(expected, "Add an action item for this gap"), - "reason": f"No action item addresses the '{cat}' contributing factor"}) - return suggestions - - def _build_theme_recommendations(self) -> Dict[str, List[str]]: - seen: Dict[str, List[str]] = {} - for a in self.five_whys: - if a.systemic_theme not in seen: - seen[a.systemic_theme] = THEME_RECS.get(a.systemic_theme, []) - return seen - - def customer_impact_summary(self) -> Dict[str, Any]: - impact = self.resolution.get("customer_impact", {}) - affected = impact.get("affected_users", 0) - failed_tx = impact.get("failed_transactions", 0) - revenue = impact.get("revenue_impact_usd", 0) - data_loss = impact.get("data_loss", False) - comm_required = affected > 1000 or data_loss or revenue > 10000 - sev = "high" if (affected > 10000 or revenue > 50000) else ( - "medium" if (affected > 1000 or revenue > 5000) else "low") - return {"affected_users": affected, "failed_transactions": failed_tx, - "revenue_impact_usd": revenue, "data_loss": data_loss, - "data_integrity": "compromised" if data_loss else "intact", - "customer_communication_required": comm_required, "impact_severity": sev} - - def executive_summary(self) -> str: - mttr = self.timeline.mttr - ci = self.customer_impact_summary() - mttr_str = f"{mttr:.0f} minutes" if mttr is not None else "unknown duration" - parts = [ - f"On {self._fmt_date(self.timeline.issue_started)}, a {self.incident.severity} " - f"incident (\"{self.incident.title}\") impacted the {self.incident.service} service.", - f"The root cause was identified as: {self.resolution.get('root_cause', 'Unknown root cause')}.", - f"The incident was resolved in {mttr_str}, affecting approximately " - f"{ci['affected_users']:,} users with an estimated revenue impact of ${ci['revenue_impact_usd']:,.2f}.", - "Data loss was confirmed; affected customers must be notified." if ci["data_loss"] - else "No data loss occurred during this incident."] - return " ".join(parts) - - @staticmethod - def _fmt_date(dt: Optional[datetime]) -> str: - return dt.strftime("%Y-%m-%d at %H:%M UTC") if dt else "an unknown date" - - def overdue_p1_items(self) -> List[Dict[str, str]]: - return [{"title": a.title, "owner": a.owner, "deadline": a.deadline} - for a in self.action_items if a.priority in ("P0", "P1") and a.is_past_deadline] - - def to_dict(self) -> Dict[str, Any]: - return { - "version": VERSION, "incident": self.incident.to_dict(), - "executive_summary": self.executive_summary(), - "timeline_metrics": self.timeline.to_dict(), - "customer_impact": self.customer_impact_summary(), - "root_cause": self.resolution.get("root_cause", ""), - "contributing_factors": [f.to_dict() for f in self.contributing_factors], - "factor_distribution": self.factor_distribution, - "five_whys_analysis": [a.to_dict() for a in self.five_whys], - "theme_recommendations": self.theme_recommendations, - "mitigation_steps": self.resolution.get("mitigation_steps", []), - "permanent_fix": self.resolution.get("permanent_fix", ""), - "action_items": [a.to_dict() for a in self.action_items], - "action_item_coverage_gaps": self.coverage_gaps, - "suggested_actions": self.suggested_actions, - "overdue_p1_items": self.overdue_p1_items(), - "participants": self.participants} - - -# ---------- Core Analysis Helpers ---------- - -def _bar(pct: float, width: int = 30) -> str: - """Render a text-based horizontal bar chart segment.""" - filled = int(round(pct / 100 * width)) - return "[" + "#" * filled + "." * (width - filled) + "]" - - -def _generate_lessons(report: PostmortemReport) -> List[str]: - """Derive lessons learned from the analysis.""" - lessons: List[str] = [] - bench = BENCHMARKS.get(report.incident.severity, BENCHMARKS["SEV3"]) - mttd = report.timeline.mttd - if mttd is not None and mttd > bench["mttd"]: - lessons.append( - f"Detection took {mttd:.0f} minutes, exceeding the {bench['mttd']}-minute " - f"benchmark for {report.incident.severity}. Invest in earlier detection mechanisms.") - dist = report.factor_distribution - dominant = max(dist, key=lambda k: dist[k]) - if dist[dominant] >= 50: - lessons.append( - f"The '{dominant}' category accounts for {dist[dominant]:.0f}% of contributing factors. " - f"Targeted improvements in this area will yield the highest return.") - if report.coverage_gaps: - lessons.append( - f"There are {len(report.coverage_gaps)} action item coverage gap(s). " - "Ensure every contributing factor category has a corresponding remediation action.") - avg_q = (sum(a.quality_score for a in report.action_items) / len(report.action_items) - if report.action_items else 0) - if avg_q < 70: - lessons.append( - f"Average action item quality score is {avg_q:.0f}/100. " - "Make action items more specific with measurable targets and clear ownership.") - if report.timeline.postmortem_on_time is False: - h = report.timeline.postmortem_timeliness_hours - lessons.append( - f"Postmortem was held {h:.0f} hours after resolution, exceeding the " - f"{POSTMORTEM_TARGET_HOURS}-hour target. Schedule postmortems sooner to capture context.") - if not lessons: - lessons.append("This incident was handled within benchmarks. Continue reinforcing " - "current practices and share this postmortem for organizational learning.") - return lessons - - -# ---------- Output Formatters ---------- - -def format_text(report: PostmortemReport) -> str: - """Format the postmortem as plain text.""" - L: List[str] = [] - W = 72 - - def h1(title: str) -> None: - L.append(""); L.append("=" * W); L.append(f" {title}"); L.append("=" * W) - - def h2(title: str) -> None: - L.append(""); L.append(f"--- {title} ---") - - inc = report.incident - h1(f"POSTMORTEM: {inc.title}") - L.append(f" ID: {inc.id} | Severity: {inc.severity} | Service: {inc.service}") - L.append(f" Commander: {inc.commander}") - if inc.affected_services: - L.append(f" Affected services: {', '.join(inc.affected_services)}") - # Executive Summary - h1("EXECUTIVE SUMMARY") - L.append("") - for sentence in report.executive_summary().split(". "): - s = sentence.strip() - if s and not s.endswith("."): s += "." - if s: L.append(f" {s}") - # Timeline Metrics - h1("TIMELINE METRICS") - tm = report.timeline - L.append("") - for label, val, unit in [("MTTD (Time to Detect)", tm.mttd, "min"), - ("MTTR (Time to Resolve)", tm.mttr, "min"), - ("Time to Mitigate", tm.time_to_mitigate, "min"), - ("Time to Declare", tm.time_to_declare, "min"), - ("Postmortem Timeliness", tm.postmortem_timeliness_hours, "hrs")]: - L.append(f" {label:<30s} {f'{val:.1f} {unit}' if val is not None else 'N/A'}") - h2("Benchmark Comparison") - for name, d in tm.benchmark_comparison().items(): - if "actual_minutes" in d: - st = "PASS" if d["met_benchmark"] else "FAIL" - L.append(f" {name:<25s} actual={d['actual_minutes']}min benchmark={d['benchmark_minutes']}min [{st}]") - elif "actual_hours" in d: - st = "PASS" if d["met_target"] else "FAIL" - L.append(f" {name:<25s} actual={d['actual_hours']}hrs target={d['target_hours']}hrs [{st}]") - # Customer Impact - h1("CUSTOMER IMPACT") - ci = report.customer_impact_summary() - L.append("") - L.append(f" Affected users: {ci['affected_users']:,}") - L.append(f" Failed transactions: {ci['failed_transactions']:,}") - L.append(f" Revenue impact: ${ci['revenue_impact_usd']:,.2f}") - L.append(f" Data integrity: {ci['data_integrity']}") - L.append(f" Impact severity: {ci['impact_severity']}") - L.append(f" Comms required: {'Yes' if ci['customer_communication_required'] else 'No'}") - # Root Cause - h1("ROOT CAUSE ANALYSIS") - L.append("") - L.append(f" {report.resolution.get('root_cause', 'Unknown')}") - h2("Contributing Factors") - for f in report.contributing_factors: - L.append(f" [{f.category.upper():<12s} w={f.weight:.2f}] {f.description}") - h2("Factor Distribution") - for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]): - if pct > 0: - L.append(f" {cat:<14s} {pct:5.1f}% {_bar(pct)}") - # 5-Whys - h1("5-WHYS ANALYSIS") - for analysis in report.five_whys: - L.append("") - L.append(f" Factor: {analysis.factor.description}") - L.append(f" Theme: {analysis.systemic_theme}") - for i, step in enumerate(analysis.chain): - L.append(f" {i}. {step}") - h2("Theme-Based Recommendations") - for theme, recs in report.theme_recommendations.items(): - L.append(f" [{theme.upper()}]") - for rec in recs: - L.append(f" - {rec}") - # Mitigation & Fix - h1("MITIGATION AND RESOLUTION") - h2("Mitigation Steps Taken") - for step in report.resolution.get("mitigation_steps", []): - L.append(f" - {step}") - h2("Permanent Fix") - L.append(f" {report.resolution.get('permanent_fix', 'TBD')}") - # Action Items - h1("ACTION ITEMS") - L.append("") - hdr = f" {'Priority':<10s} {'Type':<14s} {'Owner':<25s} {'Deadline':<12s} {'Quality':<8s} Title" - L.append(hdr) - L.append(" " + "-" * (len(hdr) - 2)) - for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)): - flag = " *OVERDUE*" if a.is_past_deadline else "" - L.append(f" {a.priority:<10s} {a.type:<14s} {a.owner:<25s} {a.deadline:<12s} " - f"{a.quality_score:<8d} {a.title}{flag}") - if report.coverage_gaps: - h2("Coverage Gaps") - for gap in report.coverage_gaps: - L.append(f" WARNING: {gap}") - if report.suggested_actions: - h2("Suggested Additional Actions") - for s in report.suggested_actions: - L.append(f" [{s['type'].upper()}] {s['suggestion']}") - L.append(f" Reason: {s['reason']}") - overdue = report.overdue_p1_items() - if overdue: - h2("Overdue P0/P1 Items") - for item in overdue: - L.append(f" OVERDUE: {item['title']} (owner: {item['owner']}, deadline: {item['deadline']})") - # Participants - h1("PARTICIPANTS") - L.append("") - for p in report.participants: - L.append(f" {p.get('name', 'Unknown'):<25s} {p.get('role', '')}") - # Lessons Learned - h1("LESSONS LEARNED") - L.append("") - for i, lesson in enumerate(_generate_lessons(report), 1): - L.append(f" {i}. {lesson}") - L.append("") - L.append("=" * W) - L.append(f" Generated by postmortem_generator v{VERSION}") - L.append("=" * W) - L.append("") - return "\n".join(L) - - -def format_json(report: PostmortemReport) -> str: - """Format the postmortem as JSON.""" - data = report.to_dict() - data["lessons_learned"] = _generate_lessons(report) - return json.dumps(data, indent=2, default=str) - - -def format_markdown(report: PostmortemReport) -> str: - """Format the postmortem as a Markdown document.""" - L: List[str] = [] - inc = report.incident - L.append(f"# Postmortem: {inc.title}") - L.append("") - L.append("| Field | Value |") - L.append("|-------|-------|") - L.append(f"| **ID** | {inc.id} |") - L.append(f"| **Severity** | {inc.severity} |") - L.append(f"| **Service** | {inc.service} |") - L.append(f"| **Commander** | {inc.commander} |") - if inc.affected_services: - L.append(f"| **Affected Services** | {', '.join(inc.affected_services)} |") - L.append("") - # Executive Summary - L.append("## Executive Summary\n") - L.append(report.executive_summary()) - L.append("") - # Timeline Metrics - L.append("## Timeline Metrics\n") - L.append("| Metric | Value | Benchmark | Status |") - L.append("|--------|-------|-----------|--------|") - labels = {"mttd": "MTTD (Time to Detect)", "mttr": "MTTR (Time to Resolve)", - "time_to_mitigate": "Time to Mitigate", "time_to_declare": "Time to Declare", - "postmortem_timeliness": "Postmortem Timeliness"} - for key, label in labels.items(): - b = report.timeline.benchmark_comparison().get(key) - if b and "actual_minutes" in b: - st = "PASS" if b["met_benchmark"] else "FAIL" - L.append(f"| {label} | {b['actual_minutes']} min | {b['benchmark_minutes']} min | {st} |") - elif b and "actual_hours" in b: - st = "PASS" if b["met_target"] else "FAIL" - L.append(f"| {label} | {b['actual_hours']} hrs | {b['target_hours']} hrs | {st} |") - L.append("") - # Customer Impact - L.append("## Customer Impact\n") - ci = report.customer_impact_summary() - L.append(f"- **Affected users:** {ci['affected_users']:,}") - L.append(f"- **Failed transactions:** {ci['failed_transactions']:,}") - L.append(f"- **Revenue impact:** ${ci['revenue_impact_usd']:,.2f}") - L.append(f"- **Data integrity:** {ci['data_integrity']}") - L.append(f"- **Impact severity:** {ci['impact_severity']}") - L.append(f"- **Customer communication required:** {'Yes' if ci['customer_communication_required'] else 'No'}") - L.append("") - # Root Cause Analysis - L.append("## Root Cause Analysis\n") - L.append(f"**Root cause:** {report.resolution.get('root_cause', 'Unknown')}") - L.append("") - L.append("### Contributing Factors\n") - L.append("| # | Category | Weight | Description |") - L.append("|---|----------|--------|-------------|") - for i, f in enumerate(report.contributing_factors, 1): - L.append(f"| {i} | {f.category} | {f.weight:.2f} | {f.description} |") - L.append("") - L.append("### Factor Distribution\n") - L.append("```") - for cat, pct in sorted(report.factor_distribution.items(), key=lambda x: -x[1]): - if pct > 0: - L.append(f" {cat:<14s} {pct:5.1f}% {_bar(pct, 25)}") - L.append("```") - L.append("") - # 5-Whys - L.append("## 5-Whys Analysis\n") - for analysis in report.five_whys: - L.append(f"### Factor: {analysis.factor.description}") - L.append(f"**Systemic theme:** {analysis.systemic_theme}\n") - for i, step in enumerate(analysis.chain): - L.append(f"{i}. {step}") - L.append("") - L.append("### Theme-Based Recommendations\n") - for theme, recs in report.theme_recommendations.items(): - L.append(f"**{theme.capitalize()}:**") - for rec in recs: - L.append(f"- {rec}") - L.append("") - # Mitigation - L.append("## Mitigation and Resolution\n") - L.append("### Mitigation Steps Taken\n") - for step in report.resolution.get("mitigation_steps", []): - L.append(f"- {step}") - L.append("") - L.append("### Permanent Fix\n") - L.append(report.resolution.get("permanent_fix", "TBD")) - L.append("") - # Action Items - L.append("## Action Items\n") - L.append("| Priority | Type | Owner | Deadline | Quality | Title |") - L.append("|----------|------|-------|----------|---------|-------|") - for a in sorted(report.action_items, key=lambda x: PRIORITY_ORDER.get(x.priority, 99)): - flag = " **OVERDUE**" if a.is_past_deadline else "" - L.append(f"| {a.priority} | {a.type} | {a.owner} | {a.deadline} | {a.quality_score}/100 | {a.title}{flag} |") - L.append("") - if report.coverage_gaps: - L.append("### Coverage Gaps\n") - for gap in report.coverage_gaps: - L.append(f"> **WARNING:** {gap}") - L.append("") - if report.suggested_actions: - L.append("### Suggested Additional Actions\n") - for s in report.suggested_actions: - L.append(f"- **[{s['type'].upper()}]** {s['suggestion']}") - L.append(f" - _Reason: {s['reason']}_") - L.append("") - overdue = report.overdue_p1_items() - if overdue: - L.append("### Overdue P0/P1 Items\n") - for item in overdue: - L.append(f"- **{item['title']}** (owner: {item['owner']}, deadline: {item['deadline']})") - L.append("") - # Participants - L.append("## Participants\n") - L.append("| Name | Role |") - L.append("|------|------|") - for p in report.participants: - L.append(f"| {p.get('name', 'Unknown')} | {p.get('role', '')} |") - L.append("") - # Lessons Learned - L.append("## Lessons Learned\n") - for i, lesson in enumerate(_generate_lessons(report), 1): - L.append(f"{i}. {lesson}") - L.append("") - L.append("---") - L.append(f"_Generated by postmortem_generator v{VERSION}_") - L.append("") - return "\n".join(L) - - -# ---------- Input Loading ---------- - -def load_input(filepath: Optional[str]) -> Dict[str, Any]: - """Load incident data from a file path or stdin.""" - if filepath: - try: - with open(filepath, "r", encoding="utf-8") as fh: - return json.load(fh) - except FileNotFoundError: - print(f"Error: File not found: {filepath}", file=sys.stderr) - sys.exit(1) - except json.JSONDecodeError as exc: - print(f"Error: Invalid JSON in {filepath}: {exc}", file=sys.stderr) - sys.exit(1) - else: - if sys.stdin.isatty(): - print("Error: No input file specified and no data on stdin.", file=sys.stderr) - print("Usage: postmortem_generator.py [data_file] or pipe JSON via stdin.", file=sys.stderr) - sys.exit(1) - try: - return json.load(sys.stdin) - except json.JSONDecodeError as exc: - print(f"Error: Invalid JSON on stdin: {exc}", file=sys.stderr) - sys.exit(1) - - -def validate_input(data: Dict[str, Any]) -> List[str]: - """Return a list of validation warnings (non-fatal).""" - warnings: List[str] = [] - for key in ("incident", "timeline", "resolution", "action_items"): - if key not in data: - warnings.append(f"Missing '{key}' section") - for ts in ("issue_started", "detected_at", "mitigated_at", "resolved_at"): - if ts not in data.get("timeline", {}): - warnings.append(f"Missing timeline field: {ts}") - res = data.get("resolution", {}) - if "root_cause" not in res: - warnings.append("Missing 'root_cause' in resolution") - if not res.get("contributing_factors"): - warnings.append("No contributing factors provided") - return warnings - - -# ---------- CLI Entry Point ---------- - -def main() -> None: - """CLI entry point for postmortem generation.""" - parser = argparse.ArgumentParser( - description="Generate structured postmortem reports with 5-Whys analysis.", - epilog="Reads JSON from a file or stdin. Outputs text, JSON, or markdown.") - parser.add_argument("data_file", nargs="?", default=None, - help="JSON file with incident + resolution data (reads stdin if omitted)") - parser.add_argument("--format", choices=["text", "json", "markdown"], default="text", - dest="output_format", help="Output format (default: text)") - args = parser.parse_args() - - data = load_input(args.data_file) - warnings = validate_input(data) - for w in warnings: - print(f"Warning: {w}", file=sys.stderr) - - report = PostmortemReport(data) - formatters = {"text": format_text, "json": format_json, "markdown": format_markdown} - print(formatters[args.output_format](report)) - - -if __name__ == "__main__": - main() diff --git a/engineering-team/skills/incident-commander/scripts/severity_classifier.py b/engineering-team/skills/incident-commander/scripts/severity_classifier.py deleted file mode 100644 index 4ce6ad62..00000000 --- a/engineering-team/skills/incident-commander/scripts/severity_classifier.py +++ /dev/null @@ -1,1228 +0,0 @@ -#!/usr/bin/env python3 -""" -Severity Classifier - Classify incident severity and generate escalation paths. - -Analyses incident data across multiple dimensions (revenue impact, user scope, -data/security risk, service criticality, blast radius) to produce a weighted -severity score and map it to SEV1-SEV4. Generates escalation paths, on-call -routing, SLA impact assessments, and immediate action plans. - -Table of Contents: - SeverityLevel - Enum-like severity definitions (SEV1-SEV4) - ImpactAssessment - Parsed impact data from incident input - SeverityScore - Multi-dimensional weighted scoring result - EscalationPath - Generated escalation routing and timelines - ActionPlan - Recommended immediate actions per severity - SLAImpact - SLA breach risk and error-budget assessment - - parse_incident_data() - Validate and normalise raw JSON input - compute_dimension_scores() - Score each weighted dimension - classify_severity() - Map composite score to SEV1-SEV4 - build_escalation_path() - Generate escalation routing - build_action_plan() - Generate immediate action checklist - assess_sla_impact() - SLA breach risk assessment - format_text() - Human-readable text output - format_json() - Machine-readable JSON output - format_markdown() - Markdown report output - main() - CLI entry point - -Usage: - python severity_classifier.py incident.json - python severity_classifier.py incident.json --format json - python severity_classifier.py incident.json --format markdown - cat incident.json | python severity_classifier.py --format text - echo '{"incident":{...}}' | python severity_classifier.py -""" - -import argparse -import json -import sys -from dataclasses import dataclass, field, asdict -from datetime import datetime, timezone -from typing import Any, Dict, List, Optional, Tuple - - -# ---------- Severity Level Definitions ---------------------------------------- - -class SeverityLevel: - """Enum-like container for SEV1 through SEV4 definitions.""" - - SEV1 = "SEV1" - SEV2 = "SEV2" - SEV3 = "SEV3" - SEV4 = "SEV4" - - DEFINITIONS: Dict[str, Dict[str, Any]] = { - "SEV1": { - "label": "Critical", - "description": ( - "Complete service outage, confirmed data loss or corruption, " - "active security breach, or more than 50% of users affected." - ), - "score_threshold": 0.75, - "response_time_minutes": 5, - "update_cadence_minutes": 15, - "executive_notify": True, - "war_room": True, - }, - "SEV2": { - "label": "Major", - "description": ( - "Significant service degradation, more than 25% of users " - "affected, no viable workaround, or high revenue impact." - ), - "score_threshold": 0.50, - "response_time_minutes": 15, - "update_cadence_minutes": 30, - "executive_notify": False, - "war_room": True, - }, - "SEV3": { - "label": "Moderate", - "description": ( - "Partial degradation with workaround available, fewer than " - "25% of users affected, limited blast radius." - ), - "score_threshold": 0.25, - "response_time_minutes": 30, - "update_cadence_minutes": 60, - "executive_notify": False, - "war_room": False, - }, - "SEV4": { - "label": "Minor", - "description": ( - "Cosmetic issue, low impact, minimal user effect, " - "informational or non-urgent." - ), - "score_threshold": 0.0, - "response_time_minutes": 120, - "update_cadence_minutes": 240, - "executive_notify": False, - "war_room": False, - }, - } - - @classmethod - def from_score(cls, score: float) -> str: - """Return the severity level string for a given composite score.""" - for level in [cls.SEV1, cls.SEV2, cls.SEV3]: - if score >= cls.DEFINITIONS[level]["score_threshold"]: - return level - return cls.SEV4 - - @classmethod - def get_definition(cls, level: str) -> Dict[str, Any]: - return cls.DEFINITIONS.get(level, cls.DEFINITIONS[cls.SEV4]) - - -# ---------- Configuration Constants ------------------------------------------- - -DIMENSION_WEIGHTS: Dict[str, float] = { - "revenue_impact": 0.25, - "user_impact_scope": 0.25, - "data_security_risk": 0.20, - "service_criticality": 0.15, - "blast_radius": 0.15, -} - -REVENUE_IMPACT_SCORES: Dict[str, float] = { - "critical": 1.0, - "high": 0.8, - "medium": 0.5, - "low": 0.2, - "none": 0.0, -} - -DEGRADATION_SCORES: Dict[str, float] = { - "complete": 1.0, - "major": 0.75, - "partial": 0.50, - "minor": 0.25, - "none": 0.0, -} - -ERROR_RATE_THRESHOLDS: List[Tuple[float, float]] = [ - (50.0, 1.0), - (25.0, 0.8), - (10.0, 0.6), - (5.0, 0.4), - (1.0, 0.2), -] - -LATENCY_P99_THRESHOLDS_MS: List[Tuple[float, float]] = [ - (10000, 1.0), - (5000, 0.8), - (2000, 0.6), - (1000, 0.4), - (500, 0.2), -] - -SLA_TIERS: Dict[str, Dict[str, Any]] = { - "SEV1": { - "target_resolution_hours": 1, - "target_response_minutes": 5, - "sla_percentage": 99.95, - "monthly_error_budget_minutes": 21.6, - }, - "SEV2": { - "target_resolution_hours": 4, - "target_response_minutes": 15, - "sla_percentage": 99.9, - "monthly_error_budget_minutes": 43.2, - }, - "SEV3": { - "target_resolution_hours": 24, - "target_response_minutes": 60, - "sla_percentage": 99.5, - "monthly_error_budget_minutes": 216.0, - }, - "SEV4": { - "target_resolution_hours": 72, - "target_response_minutes": 480, - "sla_percentage": 99.0, - "monthly_error_budget_minutes": 432.0, - }, -} - -ESCALATION_TEMPLATES: Dict[str, Dict[str, Any]] = { - "SEV1": { - "initial_notify": ["on-call-primary", "on-call-secondary", "engineering-manager"], - "escalate_after_minutes": 15, - "escalate_to": ["vp-engineering", "cto"], - "bridge_required": True, - "status_page_update": True, - "customer_comms": True, - }, - "SEV2": { - "initial_notify": ["on-call-primary", "on-call-secondary"], - "escalate_after_minutes": 30, - "escalate_to": ["engineering-manager"], - "bridge_required": True, - "status_page_update": True, - "customer_comms": False, - }, - "SEV3": { - "initial_notify": ["on-call-primary"], - "escalate_after_minutes": 120, - "escalate_to": ["on-call-secondary"], - "bridge_required": False, - "status_page_update": False, - "customer_comms": False, - }, - "SEV4": { - "initial_notify": ["on-call-primary"], - "escalate_after_minutes": 480, - "escalate_to": [], - "bridge_required": False, - "status_page_update": False, - "customer_comms": False, - }, -} - - -# ---------- Data Model Classes ------------------------------------------------ - -@dataclass -class ImpactAssessment: - """Parsed and normalised impact data from incident input.""" - - revenue_impact: str = "none" - affected_users_percentage: float = 0.0 - affected_regions: List[str] = field(default_factory=list) - data_integrity_risk: bool = False - security_breach: bool = False - customer_facing: bool = False - degradation_type: str = "none" - workaround_available: bool = True - - -@dataclass -class SeverityScore: - """Multi-dimensional scoring result with per-dimension breakdown.""" - - composite_score: float = 0.0 - severity_level: str = SeverityLevel.SEV4 - dimensions: Dict[str, float] = field(default_factory=dict) - weighted_dimensions: Dict[str, float] = field(default_factory=dict) - contributing_factors: List[str] = field(default_factory=list) - auto_escalate_reasons: List[str] = field(default_factory=list) - - -@dataclass -class EscalationPath: - """Generated escalation routing and notification schedule.""" - - severity_level: str = SeverityLevel.SEV4 - immediate_notify: List[str] = field(default_factory=list) - escalation_chain: List[Dict[str, Any]] = field(default_factory=list) - cross_team_notify: List[str] = field(default_factory=list) - war_room_required: bool = False - bridge_link: str = "" - status_page_update: bool = False - customer_comms_required: bool = False - suggested_smes: List[str] = field(default_factory=list) - - -@dataclass -class ActionPlan: - """Recommended immediate actions checklist for the incident.""" - - severity_level: str = SeverityLevel.SEV4 - immediate_actions: List[str] = field(default_factory=list) - diagnostic_steps: List[str] = field(default_factory=list) - communication_actions: List[str] = field(default_factory=list) - rollback_assessment: Dict[str, Any] = field(default_factory=dict) - - -@dataclass -class SLAImpact: - """SLA breach risk and error-budget assessment.""" - - severity_level: str = SeverityLevel.SEV4 - sla_tier: Dict[str, Any] = field(default_factory=dict) - breach_risk: str = "low" - error_budget_impact_minutes: float = 0.0 - remaining_budget_percentage: float = 100.0 - estimated_time_to_breach_minutes: float = 0.0 - recommendations: List[str] = field(default_factory=list) - - -# ---------- Input Parsing ----------------------------------------------------- - -def parse_incident_data(raw: Dict[str, Any]) -> Tuple[Dict, ImpactAssessment, Dict, Dict]: - """ - Validate and normalise raw JSON input into typed structures. - - Returns: - (incident_info, impact_assessment, signals, context) - """ - incident = raw.get("incident", {}) - if not incident: - raise ValueError("Input must contain an 'incident' key with title and description.") - - impact_raw = raw.get("impact", {}) - impact = ImpactAssessment( - revenue_impact=impact_raw.get("revenue_impact", "none"), - affected_users_percentage=float(impact_raw.get("affected_users_percentage", 0)), - affected_regions=impact_raw.get("affected_regions", []), - data_integrity_risk=bool(impact_raw.get("data_integrity_risk", False)), - security_breach=bool(impact_raw.get("security_breach", False)), - customer_facing=bool(impact_raw.get("customer_facing", False)), - degradation_type=impact_raw.get("degradation_type", "none"), - workaround_available=bool(impact_raw.get("workaround_available", True)), - ) - - signals = raw.get("signals", {}) - context = raw.get("context", {}) - - return incident, impact, signals, context - - -# ---------- Core Scoring Engine ----------------------------------------------- - -def _score_revenue_impact(impact: ImpactAssessment) -> Tuple[float, List[str]]: - """Score the revenue impact dimension (0.0 - 1.0).""" - factors: List[str] = [] - score = REVENUE_IMPACT_SCORES.get(impact.revenue_impact, 0.0) - - if impact.customer_facing and score >= 0.5: - score = min(1.0, score + 0.1) - factors.append("Customer-facing service with revenue exposure") - - if not impact.workaround_available and score >= 0.5: - score = min(1.0, score + 0.1) - factors.append("No workaround available, prolonging revenue impact") - - if score >= 0.8: - factors.append(f"Revenue impact rated '{impact.revenue_impact}'") - - return score, factors - - -def _score_user_impact(impact: ImpactAssessment, signals: Dict) -> Tuple[float, List[str]]: - """Score the user impact scope dimension (0.0 - 1.0).""" - factors: List[str] = [] - pct = impact.affected_users_percentage - - if pct >= 75: - score = 1.0 - elif pct >= 50: - score = 0.85 - elif pct >= 25: - score = 0.65 - elif pct >= 10: - score = 0.45 - elif pct >= 1: - score = 0.25 - else: - score = 0.1 - - if pct > 0: - factors.append(f"{pct}% of users affected") - - customer_reports = signals.get("customer_reports", 0) - if customer_reports > 20: - score = min(1.0, score + 0.15) - factors.append(f"{customer_reports} customer reports received") - elif customer_reports > 5: - score = min(1.0, score + 0.08) - factors.append(f"{customer_reports} customer reports received") - - degradation_boost = DEGRADATION_SCORES.get(impact.degradation_type, 0.0) * 0.15 - score = min(1.0, score + degradation_boost) - if impact.degradation_type in ("complete", "major"): - factors.append(f"Degradation type: {impact.degradation_type}") - - return score, factors - - -def _score_data_security(impact: ImpactAssessment) -> Tuple[float, List[str]]: - """Score the data/security risk dimension (0.0 - 1.0).""" - factors: List[str] = [] - score = 0.0 - - if impact.security_breach: - score = 1.0 - factors.append("Active security breach confirmed") - elif impact.data_integrity_risk: - score = 0.8 - factors.append("Data integrity at risk") - - if impact.customer_facing and impact.data_integrity_risk: - score = min(1.0, score + 0.1) - factors.append("Customer data potentially affected") - - return score, factors - - -def _score_service_criticality(signals: Dict, context: Dict) -> Tuple[float, List[str]]: - """Score service criticality based on signals and dependency graph.""" - factors: List[str] = [] - score = 0.0 - - dependent_services = signals.get("dependent_services", []) - dep_count = len(dependent_services) - if dep_count >= 5: - score = 1.0 - factors.append(f"{dep_count} dependent services (critical hub)") - elif dep_count >= 3: - score = 0.75 - factors.append(f"{dep_count} dependent services") - elif dep_count >= 1: - score = 0.5 - factors.append(f"{dep_count} dependent service(s)") - else: - score = 0.2 - - affected_endpoints = signals.get("affected_endpoints", []) - if len(affected_endpoints) >= 5: - score = min(1.0, score + 0.15) - factors.append(f"{len(affected_endpoints)} endpoints affected") - elif len(affected_endpoints) >= 2: - score = min(1.0, score + 0.08) - factors.append(f"{len(affected_endpoints)} endpoints affected") - - return score, factors - - -def _score_blast_radius( - impact: ImpactAssessment, signals: Dict -) -> Tuple[float, List[str]]: - """Score blast radius from region spread, alert volume, and error rate.""" - factors: List[str] = [] - score = 0.0 - - region_count = len(impact.affected_regions) - if region_count >= 3: - score = 0.9 - factors.append(f"Spanning {region_count} regions") - elif region_count == 2: - score = 0.6 - factors.append(f"Spanning {region_count} regions") - elif region_count == 1: - score = 0.3 - - error_rate = signals.get("error_rate_percentage", 0.0) - for threshold, rate_score in ERROR_RATE_THRESHOLDS: - if error_rate >= threshold: - score = max(score, rate_score) - factors.append(f"Error rate at {error_rate}%") - break - - latency = signals.get("latency_p99_ms", 0) - for threshold, lat_score in LATENCY_P99_THRESHOLDS_MS: - if latency >= threshold: - score = max(score, lat_score) - factors.append(f"P99 latency at {latency}ms") - break - - alert_count = signals.get("alert_count", 0) - if alert_count >= 20: - score = min(1.0, score + 0.15) - factors.append(f"{alert_count} alerts firing") - elif alert_count >= 10: - score = min(1.0, score + 0.08) - factors.append(f"{alert_count} alerts firing") - - return score, factors - - -def compute_dimension_scores( - impact: ImpactAssessment, signals: Dict, context: Dict -) -> SeverityScore: - """Score each weighted dimension and produce a composite severity score.""" - dimensions: Dict[str, float] = {} - weighted: Dict[str, float] = {} - all_factors: List[str] = [] - auto_escalate: List[str] = [] - - # -- Revenue impact -- - rev_score, rev_factors = _score_revenue_impact(impact) - dimensions["revenue_impact"] = round(rev_score, 3) - weighted["revenue_impact"] = round(rev_score * DIMENSION_WEIGHTS["revenue_impact"], 3) - all_factors.extend(rev_factors) - - # -- User impact scope -- - user_score, user_factors = _score_user_impact(impact, signals) - dimensions["user_impact_scope"] = round(user_score, 3) - weighted["user_impact_scope"] = round(user_score * DIMENSION_WEIGHTS["user_impact_scope"], 3) - all_factors.extend(user_factors) - - # -- Data / security risk -- - sec_score, sec_factors = _score_data_security(impact) - dimensions["data_security_risk"] = round(sec_score, 3) - weighted["data_security_risk"] = round(sec_score * DIMENSION_WEIGHTS["data_security_risk"], 3) - all_factors.extend(sec_factors) - - # -- Service criticality -- - svc_score, svc_factors = _score_service_criticality(signals, context) - dimensions["service_criticality"] = round(svc_score, 3) - weighted["service_criticality"] = round(svc_score * DIMENSION_WEIGHTS["service_criticality"], 3) - all_factors.extend(svc_factors) - - # -- Blast radius -- - blast_score, blast_factors = _score_blast_radius(impact, signals) - dimensions["blast_radius"] = round(blast_score, 3) - weighted["blast_radius"] = round(blast_score * DIMENSION_WEIGHTS["blast_radius"], 3) - all_factors.extend(blast_factors) - - composite = sum(weighted.values()) - - # -- Auto-escalation overrides -- - if impact.security_breach: - composite = max(composite, 0.85) - auto_escalate.append("Security breach triggers automatic SEV1 escalation") - if impact.data_integrity_risk and impact.customer_facing: - composite = max(composite, 0.76) - auto_escalate.append("Customer-facing data integrity risk triggers SEV1 floor") - if impact.affected_users_percentage >= 50 and impact.degradation_type == "complete": - composite = max(composite, 0.80) - auto_escalate.append("Complete outage affecting 50%+ users triggers SEV1 floor") - - composite = min(1.0, round(composite, 3)) - severity_level = SeverityLevel.from_score(composite) - - return SeverityScore( - composite_score=composite, - severity_level=severity_level, - dimensions=dimensions, - weighted_dimensions=weighted, - contributing_factors=all_factors, - auto_escalate_reasons=auto_escalate, - ) - - -# ---------- Classification Wrapper -------------------------------------------- - -def classify_severity( - incident: Dict, impact: ImpactAssessment, signals: Dict, context: Dict -) -> SeverityScore: - """ - Top-level classification: compute scores and return the final - SeverityScore including the resolved severity level. - """ - return compute_dimension_scores(impact, signals, context) - - -# ---------- Escalation Path Builder ------------------------------------------- - -def build_escalation_path( - severity_score: SeverityScore, - signals: Dict, - context: Dict, -) -> EscalationPath: - """Generate the escalation routing based on severity and context.""" - level = severity_score.severity_level - template = ESCALATION_TEMPLATES.get(level, ESCALATION_TEMPLATES["SEV4"]) - - on_call = context.get("on_call", {}) - primary = on_call.get("primary", "on-call-primary@company.com") - secondary = on_call.get("secondary", "on-call-secondary@company.com") - - immediate: List[str] = [] - for role in template["initial_notify"]: - if role == "on-call-primary": - immediate.append(primary) - elif role == "on-call-secondary": - immediate.append(secondary) - else: - immediate.append(role) - - chain: List[Dict[str, Any]] = [] - if template["escalate_to"]: - chain.append({ - "trigger_after_minutes": template["escalate_after_minutes"], - "notify": template["escalate_to"], - "reason": f"No resolution within {template['escalate_after_minutes']} minutes", - }) - - sev_def = SeverityLevel.get_definition(level) - if sev_def.get("executive_notify"): - chain.append({ - "trigger_after_minutes": 15, - "notify": ["vp-engineering", "cto"], - "reason": "SEV1 executive notification policy", - }) - - cross_team: List[str] = [] - dependent_services = signals.get("dependent_services", []) - for svc in dependent_services: - cross_team.append(f"{svc}-team") - - suggested_smes: List[str] = [] - affected_endpoints = signals.get("affected_endpoints", []) - if affected_endpoints: - suggested_smes.append(f"API owner for: {', '.join(affected_endpoints[:3])}") - if dependent_services: - suggested_smes.append(f"Service owners: {', '.join(dependent_services[:3])}") - - ongoing = context.get("ongoing_incidents", []) - if ongoing: - suggested_smes.append("Incident coordinator (multiple active incidents)") - - bridge_link = "" - if template["bridge_required"]: - bridge_link = f"https://bridge.company.com/incident-{level.lower()}" - - return EscalationPath( - severity_level=level, - immediate_notify=immediate, - escalation_chain=chain, - cross_team_notify=cross_team, - war_room_required=template["bridge_required"], - bridge_link=bridge_link, - status_page_update=template["status_page_update"], - customer_comms_required=template.get("customer_comms", False), - suggested_smes=suggested_smes, - ) - - -# ---------- Action Plan Builder ----------------------------------------------- - -def build_action_plan( - severity_score: SeverityScore, - incident: Dict, - impact: ImpactAssessment, - signals: Dict, - context: Dict, -) -> ActionPlan: - """Generate the immediate action plan for the classified incident.""" - level = severity_score.severity_level - sev_def = SeverityLevel.get_definition(level) - - # -- Immediate actions -- - immediate: List[str] = [ - f"Acknowledge incident within {sev_def['response_time_minutes']} minutes", - "Join the war room / bridge call" if sev_def["war_room"] else "Open incident channel", - f"Post status update every {sev_def['update_cadence_minutes']} minutes", - ] - - if level in (SeverityLevel.SEV1, SeverityLevel.SEV2): - immediate.append("Page secondary on-call if primary unresponsive within 5 minutes") - immediate.append("Begin impact quantification for executive update") - - if impact.security_breach: - immediate.insert(0, "CRITICAL: Initiate security incident response playbook") - immediate.append("Engage security team immediately") - immediate.append("Preserve forensic evidence -- do not restart services yet") - - if impact.data_integrity_risk: - immediate.append("Halt writes to affected data stores if safe to do so") - immediate.append("Begin data integrity verification") - - # -- Diagnostic steps -- - diagnostics: List[str] = [ - "Check service dashboards and recent metric trends", - "Review application logs for error spikes", - "Verify upstream and downstream dependency health", - ] - - error_rate = signals.get("error_rate_percentage", 0) - if error_rate > 10: - diagnostics.append(f"Investigate error rate spike ({error_rate}%)") - - latency = signals.get("latency_p99_ms", 0) - if latency > 2000: - diagnostics.append(f"Investigate latency degradation (P99 = {latency}ms)") - - affected_endpoints = signals.get("affected_endpoints", []) - if affected_endpoints: - diagnostics.append( - f"Trace requests to affected endpoints: {', '.join(affected_endpoints[:5])}" - ) - - dependent_services = signals.get("dependent_services", []) - if dependent_services: - diagnostics.append( - f"Check health of dependent services: {', '.join(dependent_services)}" - ) - - # -- Communication actions -- - comms: List[str] = [] - if sev_def.get("executive_notify"): - comms.append("Draft executive summary within 15 minutes") - if level in (SeverityLevel.SEV1, SeverityLevel.SEV2): - comms.append("Post initial status page update") - comms.append("Notify customer success team for proactive outreach") - comms.append(f"Schedule post-incident review within 48 hours") - - # -- Rollback assessment -- - recent_deploys = context.get("recent_deployments", []) - rollback: Dict[str, Any] = {"recent_deployment_detected": False, "recommendation": ""} - - if recent_deploys: - latest = recent_deploys[0] - rollback["recent_deployment_detected"] = True - rollback["service"] = latest.get("service", "unknown") - rollback["version"] = latest.get("version", "unknown") - rollback["deployed_at"] = latest.get("deployed_at", "unknown") - - detected_at = incident.get("detected_at", "") - deploy_time = latest.get("deployed_at", "") - if detected_at and deploy_time: - try: - det = datetime.fromisoformat(detected_at.replace("Z", "+00:00")) - dep = datetime.fromisoformat(deploy_time.replace("Z", "+00:00")) - delta_minutes = (det - dep).total_seconds() / 60 - rollback["minutes_since_deploy"] = round(delta_minutes, 1) - if 0 < delta_minutes < 120: - rollback["recommendation"] = ( - f"STRONG: Deployment of {latest.get('service')} v{latest.get('version')} " - f"occurred {round(delta_minutes)} minutes before detection. " - "Consider immediate rollback." - ) - else: - rollback["recommendation"] = ( - "Recent deployment is outside the typical correlation window. " - "Investigate other root causes first." - ) - except (ValueError, TypeError): - rollback["recommendation"] = ( - "Unable to parse timestamps. Manually assess deployment correlation." - ) - else: - rollback["recommendation"] = ( - "No recent deployments detected. Focus on infrastructure and dependency investigation." - ) - - return ActionPlan( - severity_level=level, - immediate_actions=immediate, - diagnostic_steps=diagnostics, - communication_actions=comms, - rollback_assessment=rollback, - ) - - -# ---------- SLA Impact Assessment --------------------------------------------- - -def assess_sla_impact( - severity_score: SeverityScore, - impact: ImpactAssessment, - signals: Dict, -) -> SLAImpact: - """Calculate SLA breach risk and error-budget consumption.""" - level = severity_score.severity_level - tier = SLA_TIERS.get(level, SLA_TIERS["SEV4"]) - - # Estimate ongoing burn rate (minutes of budget consumed per real minute) - user_pct = impact.affected_users_percentage / 100.0 - degradation_factor = DEGRADATION_SCORES.get(impact.degradation_type, 0.25) - burn_rate = user_pct * degradation_factor - if burn_rate <= 0: - burn_rate = 0.01 # minimum if incident is open - - monthly_budget = tier["monthly_error_budget_minutes"] - - # Assume 30% of budget already consumed this month for conservative estimate - assumed_consumed_pct = 30.0 - remaining_budget = monthly_budget * (1 - assumed_consumed_pct / 100.0) - - if burn_rate > 0: - time_to_breach = remaining_budget / burn_rate - else: - time_to_breach = float("inf") - - # Classify breach risk - if time_to_breach <= 30: - breach_risk = "critical" - elif time_to_breach <= 120: - breach_risk = "high" - elif time_to_breach <= 480: - breach_risk = "medium" - else: - breach_risk = "low" - - budget_impact_per_hour = burn_rate * 60 - error_budget_impact = round(budget_impact_per_hour, 2) - - remaining_pct = round( - max(0.0, (remaining_budget / monthly_budget) * 100.0), 1 - ) - - recommendations: List[str] = [] - if breach_risk == "critical": - recommendations.append( - "SLA breach imminent. Prioritize resolution above all other work." - ) - recommendations.append( - "Prepare customer communication about potential SLA credit." - ) - elif breach_risk == "high": - recommendations.append( - "SLA breach likely within hours. Escalate to ensure rapid resolution." - ) - elif breach_risk == "medium": - recommendations.append( - "Monitor error budget consumption. Resolve before end of business." - ) - else: - recommendations.append( - "SLA impact is contained. Continue standard incident response." - ) - - recommendations.append( - f"Current burn rate: {round(burn_rate * 100, 1)}% of error budget per minute" - ) - recommendations.append( - f"Estimated time to SLA breach: {round(time_to_breach, 0)} minutes " - f"({round(time_to_breach / 60, 1)} hours)" - ) - - return SLAImpact( - severity_level=level, - sla_tier=tier, - breach_risk=breach_risk, - error_budget_impact_minutes=error_budget_impact, - remaining_budget_percentage=remaining_pct, - estimated_time_to_breach_minutes=round(time_to_breach, 1), - recommendations=recommendations, - ) - - -# ---------- Output Formatters ------------------------------------------------- - -def _header_line(char: str, width: int = 72) -> str: - return char * width - - -def format_text( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a human-readable text report.""" - lines: List[str] = [] - w = 72 - - lines.append(_header_line("=", w)) - lines.append("INCIDENT SEVERITY CLASSIFICATION REPORT") - lines.append(_header_line("=", w)) - lines.append("") - - # -- Incident Summary -- - lines.append(f"Title: {incident.get('title', 'N/A')}") - lines.append(f"Service: {incident.get('service', 'N/A')}") - lines.append(f"Detected: {incident.get('detected_at', 'N/A')}") - lines.append(f"Reporter: {incident.get('reporter', 'N/A')}") - lines.append("") - - # -- Severity -- - sev_def = SeverityLevel.get_definition(severity_score.severity_level) - lines.append(_header_line("-", w)) - lines.append(f"SEVERITY: {severity_score.severity_level} ({sev_def['label']})") - lines.append(f"Composite Score: {severity_score.composite_score:.3f}") - lines.append(_header_line("-", w)) - lines.append(f" {sev_def['description']}") - lines.append("") - - # -- Dimension Breakdown -- - lines.append("Dimension Scores:") - for dim, raw in severity_score.dimensions.items(): - wt = severity_score.weighted_dimensions.get(dim, 0) - weight_cfg = DIMENSION_WEIGHTS.get(dim, 0) - label = dim.replace("_", " ").title() - lines.append(f" {label:<25s} raw={raw:.3f} weight={weight_cfg:.2f} weighted={wt:.3f}") - lines.append("") - - if severity_score.contributing_factors: - lines.append("Contributing Factors:") - for f in severity_score.contributing_factors: - lines.append(f" - {f}") - lines.append("") - - if severity_score.auto_escalate_reasons: - lines.append("Auto-Escalation Overrides:") - for r in severity_score.auto_escalate_reasons: - lines.append(f" * {r}") - lines.append("") - - # -- Escalation Path -- - lines.append(_header_line("-", w)) - lines.append("ESCALATION PATH") - lines.append(_header_line("-", w)) - lines.append(f"Immediate Notify: {', '.join(escalation.immediate_notify)}") - if escalation.war_room_required: - lines.append(f"War Room: Required ({escalation.bridge_link})") - else: - lines.append("War Room: Not required") - lines.append(f"Status Page: {'Update required' if escalation.status_page_update else 'No update needed'}") - lines.append(f"Customer Comms: {'Required' if escalation.customer_comms_required else 'Not required'}") - lines.append("") - - if escalation.escalation_chain: - lines.append("Escalation Chain:") - for step in escalation.escalation_chain: - lines.append( - f" After {step['trigger_after_minutes']}min -> " - f"Notify: {', '.join(step['notify'])} ({step['reason']})" - ) - lines.append("") - - if escalation.cross_team_notify: - lines.append(f"Cross-Team Notify: {', '.join(escalation.cross_team_notify)}") - if escalation.suggested_smes: - lines.append("Suggested SMEs:") - for sme in escalation.suggested_smes: - lines.append(f" - {sme}") - lines.append("") - - # -- Action Plan -- - lines.append(_header_line("-", w)) - lines.append("ACTION PLAN") - lines.append(_header_line("-", w)) - - lines.append("Immediate Actions:") - for i, action in enumerate(action_plan.immediate_actions, 1): - lines.append(f" {i}. {action}") - lines.append("") - - lines.append("Diagnostic Steps:") - for i, step in enumerate(action_plan.diagnostic_steps, 1): - lines.append(f" {i}. {step}") - lines.append("") - - lines.append("Communication Actions:") - for i, action in enumerate(action_plan.communication_actions, 1): - lines.append(f" {i}. {action}") - lines.append("") - - rb = action_plan.rollback_assessment - lines.append("Rollback Assessment:") - if rb.get("recent_deployment_detected"): - lines.append(f" Recent Deploy: {rb.get('service', '?')} v{rb.get('version', '?')}") - lines.append(f" Deployed At: {rb.get('deployed_at', '?')}") - if "minutes_since_deploy" in rb: - lines.append(f" Minutes Before Detection: {rb['minutes_since_deploy']}") - lines.append(f" Recommendation: {rb.get('recommendation', 'N/A')}") - lines.append("") - - # -- SLA Impact -- - lines.append(_header_line("-", w)) - lines.append("SLA IMPACT ASSESSMENT") - lines.append(_header_line("-", w)) - lines.append(f"Breach Risk: {sla_impact.breach_risk.upper()}") - lines.append(f"Error Budget Impact: {sla_impact.error_budget_impact_minutes} min/hr") - lines.append(f"Remaining Budget: {sla_impact.remaining_budget_percentage}%") - lines.append(f"Est. Time to Breach: {sla_impact.estimated_time_to_breach_minutes} min") - tier = sla_impact.sla_tier - lines.append(f"Target Resolution: {tier.get('target_resolution_hours', '?')} hours") - lines.append(f"Target Response: {tier.get('target_response_minutes', '?')} minutes") - lines.append("") - - if sla_impact.recommendations: - lines.append("SLA Recommendations:") - for rec in sla_impact.recommendations: - lines.append(f" - {rec}") - lines.append("") - lines.append(_header_line("=", w)) - - return "\n".join(lines) - - -def format_json( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a machine-readable JSON report.""" - report = { - "classification_timestamp": datetime.now(timezone.utc).isoformat(), - "incident": incident, - "severity": asdict(severity_score), - "severity_definition": SeverityLevel.get_definition(severity_score.severity_level), - "escalation": asdict(escalation), - "action_plan": asdict(action_plan), - "sla_impact": asdict(sla_impact), - } - return json.dumps(report, indent=2, default=str) - - -def format_markdown( - incident: Dict, - severity_score: SeverityScore, - escalation: EscalationPath, - action_plan: ActionPlan, - sla_impact: SLAImpact, -) -> str: - """Render a Markdown report suitable for incident tickets or wikis.""" - lines: List[str] = [] - sev_def = SeverityLevel.get_definition(severity_score.severity_level) - - lines.append(f"# Incident Severity Classification: {severity_score.severity_level}") - lines.append("") - lines.append(f"**Classified:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}") - lines.append("") - - lines.append("## Incident Summary") - lines.append("") - lines.append(f"| Field | Value |") - lines.append(f"|-------|-------|") - lines.append(f"| Title | {incident.get('title', 'N/A')} |") - lines.append(f"| Service | {incident.get('service', 'N/A')} |") - lines.append(f"| Detected | {incident.get('detected_at', 'N/A')} |") - lines.append(f"| Reporter | {incident.get('reporter', 'N/A')} |") - lines.append("") - - lines.append("## Severity Classification") - lines.append("") - lines.append( - f"> **{severity_score.severity_level} -- {sev_def['label']}** " - f"(Score: {severity_score.composite_score:.3f})" - ) - lines.append(f">") - lines.append(f"> {sev_def['description']}") - lines.append("") - - lines.append("### Dimension Scores") - lines.append("") - lines.append("| Dimension | Raw | Weight | Weighted |") - lines.append("|-----------|-----|--------|----------|") - for dim, raw in severity_score.dimensions.items(): - wt = severity_score.weighted_dimensions.get(dim, 0) - weight_cfg = DIMENSION_WEIGHTS.get(dim, 0) - label = dim.replace("_", " ").title() - lines.append(f"| {label} | {raw:.3f} | {weight_cfg:.2f} | {wt:.3f} |") - lines.append("") - - if severity_score.contributing_factors: - lines.append("### Contributing Factors") - lines.append("") - for f in severity_score.contributing_factors: - lines.append(f"- {f}") - lines.append("") - - if severity_score.auto_escalate_reasons: - lines.append("### Auto-Escalation Overrides") - lines.append("") - for r in severity_score.auto_escalate_reasons: - lines.append(f"- **{r}**") - lines.append("") - - lines.append("## Escalation Path") - lines.append("") - lines.append(f"**Immediate Notify:** {', '.join(escalation.immediate_notify)}") - lines.append("") - - if escalation.war_room_required: - lines.append(f"**War Room:** [Join Bridge]({escalation.bridge_link})") - else: - lines.append("**War Room:** Not required") - lines.append("") - - if escalation.escalation_chain: - lines.append("### Escalation Chain") - lines.append("") - for step in escalation.escalation_chain: - lines.append( - f"- **After {step['trigger_after_minutes']} min:** " - f"Notify {', '.join(step['notify'])} -- {step['reason']}" - ) - lines.append("") - - if escalation.cross_team_notify: - lines.append(f"**Cross-Team:** {', '.join(escalation.cross_team_notify)}") - lines.append("") - - if escalation.suggested_smes: - lines.append("### Suggested SMEs") - lines.append("") - for sme in escalation.suggested_smes: - lines.append(f"- {sme}") - lines.append("") - - lines.append("## Action Plan") - lines.append("") - - lines.append("### Immediate Actions") - lines.append("") - for i, action in enumerate(action_plan.immediate_actions, 1): - lines.append(f"{i}. {action}") - lines.append("") - - lines.append("### Diagnostic Steps") - lines.append("") - for i, step in enumerate(action_plan.diagnostic_steps, 1): - lines.append(f"{i}. {step}") - lines.append("") - - lines.append("### Communication") - lines.append("") - for i, action in enumerate(action_plan.communication_actions, 1): - lines.append(f"{i}. {action}") - lines.append("") - - rb = action_plan.rollback_assessment - lines.append("### Rollback Assessment") - lines.append("") - if rb.get("recent_deployment_detected"): - lines.append( - f"| Deploy | {rb.get('service', '?')} v{rb.get('version', '?')} |" - ) - lines.append(f"|--------|------|") - lines.append(f"| Deployed At | {rb.get('deployed_at', '?')} |") - if "minutes_since_deploy" in rb: - lines.append(f"| Minutes Before Detection | {rb['minutes_since_deploy']} |") - lines.append("") - lines.append(f"**Recommendation:** {rb.get('recommendation', 'N/A')}") - lines.append("") - - lines.append("## SLA Impact") - lines.append("") - tier = sla_impact.sla_tier - lines.append(f"| Metric | Value |") - lines.append(f"|--------|-------|") - lines.append(f"| Breach Risk | **{sla_impact.breach_risk.upper()}** |") - lines.append(f"| Error Budget Impact | {sla_impact.error_budget_impact_minutes} min/hr |") - lines.append(f"| Remaining Budget | {sla_impact.remaining_budget_percentage}% |") - lines.append(f"| Est. Time to Breach | {sla_impact.estimated_time_to_breach_minutes} min |") - lines.append(f"| Target Resolution | {tier.get('target_resolution_hours', '?')} hours |") - lines.append(f"| Target Response | {tier.get('target_response_minutes', '?')} minutes |") - lines.append("") - - if sla_impact.recommendations: - lines.append("### SLA Recommendations") - lines.append("") - for rec in sla_impact.recommendations: - lines.append(f"- {rec}") - lines.append("") - - lines.append("---") - lines.append("*Generated by severity_classifier.py*") - - return "\n".join(lines) - - -# ---------- CLI Entry Point --------------------------------------------------- - -def main() -> None: - """Parse arguments, read input, classify, and emit output.""" - parser = argparse.ArgumentParser( - description="Classify incident severity and generate escalation paths.", - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog="""\ -examples: - %(prog)s incident.json - %(prog)s incident.json --format json - %(prog)s incident.json --format markdown - cat incident.json | %(prog)s - cat incident.json | %(prog)s --format json -""", - ) - - parser.add_argument( - "data_file", - nargs="?", - default=None, - help="JSON file with incident data (reads stdin if omitted)", - ) - parser.add_argument( - "--format", - choices=["text", "json", "markdown"], - default="text", - dest="output_format", - help="Output format (default: text)", - ) - - args = parser.parse_args() - - # -- Read input -- - try: - if args.data_file: - with open(args.data_file, "r", encoding="utf-8") as fh: - raw_data = json.load(fh) - else: - if sys.stdin.isatty(): - parser.error("No input file provided and stdin is a terminal. Pipe JSON or pass a file.") - raw_data = json.load(sys.stdin) - except json.JSONDecodeError as exc: - print(f"Error: invalid JSON input -- {exc}", file=sys.stderr) - sys.exit(1) - except FileNotFoundError: - print(f"Error: file not found -- {args.data_file}", file=sys.stderr) - sys.exit(1) - except IOError as exc: - print(f"Error: could not read input -- {exc}", file=sys.stderr) - sys.exit(1) - - # -- Parse and validate -- - try: - incident, impact, signals, context = parse_incident_data(raw_data) - except ValueError as exc: - print(f"Error: {exc}", file=sys.stderr) - sys.exit(1) - - # -- Classify -- - severity_score = classify_severity(incident, impact, signals, context) - - # -- Build outputs -- - escalation = build_escalation_path(severity_score, signals, context) - action_plan = build_action_plan(severity_score, incident, impact, signals, context) - sla_impact = assess_sla_impact(severity_score, impact, signals) - - # -- Format and print -- - if args.output_format == "json": - output = format_json(incident, severity_score, escalation, action_plan, sla_impact) - elif args.output_format == "markdown": - output = format_markdown(incident, severity_score, escalation, action_plan, sla_impact) - else: - output = format_text(incident, severity_score, escalation, action_plan, sla_impact) - - print(output) - - # -- Exit code reflects severity -- - if severity_score.severity_level == SeverityLevel.SEV1: - sys.exit(2) - elif severity_score.severity_level == SeverityLevel.SEV2: - sys.exit(1) - else: - sys.exit(0) - - -if __name__ == "__main__": - main() diff --git a/engineering-team/skills/ms365-tenant-manager/SKILL.md b/engineering-team/skills/ms365-tenant-manager/SKILL.md index e24ebc33..7da2f3cb 100644 --- a/engineering-team/skills/ms365-tenant-manager/SKILL.md +++ b/engineering-team/skills/ms365-tenant-manager/SKILL.md @@ -43,6 +43,28 @@ $policy = @{ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy ``` +### Bundled Python Generators + +Three stdlib tools generate the PowerShell artifacts deterministically — prefer them over hand-writing scripts for bulk/repeatable work. Sample input: `sample_input.json`; expected shape: `expected_output.json`. + +```bash +# Tenant setup: checklist + DNS records + license plan (JSON), or the full setup script +python3 scripts/tenant_setup.py --config sample_input.json --format json -o tenant_plan.json +python3 scripts/tenant_setup.py --config sample_input.json --format powershell -o tenant_setup.ps1 + +# User lifecycle: validate first, then generate creation/offboarding scripts +python3 scripts/user_management.py --domain acme.com --action validate --users users.json +python3 scripts/user_management.py --domain acme.com --action create --users users.json -o create_users.ps1 +python3 scripts/user_management.py --domain acme.com --action offboard --user-email jane@acme.com -o offboard.ps1 + +# Admin scripts: CA policy / security audit / bulk licensing +python3 scripts/powershell_generator.py --tenant-domain acme.com --task conditional-access --policy-config policy.json -o ca_policy.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task security-audit -o audit.ps1 +python3 scripts/powershell_generator.py --tenant-domain acme.com --task bulk-license --users-csv users.csv --license-sku ENTERPRISEPACK -o licenses.ps1 +``` + +**Gate:** for user creation, run `--action validate` first and require every entry to report `"is_valid": true` before generating the creation script. Review every generated `.ps1` against the workflows below before running it in the tenant. + --- ## Workflows @@ -51,6 +73,8 @@ New-MgIdentityConditionalAccessPolicy -BodyParameter $policy **Step 1: Generate Setup Checklist** +Run `python3 scripts/tenant_setup.py --config tenant.json --format json` and work through `setup_checklist` phase by phase; `dns_records` feeds Step 2 and `license_recommendations` feeds the licensing workflow. + Confirm prerequisites before provisioning: - Global Admin account created and secured with MFA - Custom domain purchased and accessible for DNS edits diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py b/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py index 9ea68742..29a5b6cc 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/powershell_generator.py @@ -428,3 +428,47 @@ Write-Host "Results saved to: $resultsPath" -ForegroundColor Cyan Disconnect-MgGraph """ return script + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate ready-to-run M365 admin PowerShell scripts (Graph SDK based)" + ) + parser.add_argument("--tenant-domain", required=True, help="Primary tenant domain (e.g. acme.com)") + parser.add_argument("--task", required=True, + choices=["conditional-access", "security-audit", "bulk-license"], + help="Which script to generate") + parser.add_argument("--policy-config", help="Policy config JSON file (conditional-access)") + parser.add_argument("--users-csv", help="Users CSV path baked into the script (bulk-license)") + parser.add_argument("--license-sku", help="License SKU (bulk-license)") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + generator = PowerShellScriptGenerator(args.tenant_domain) + + if args.task == "conditional-access": + policy = {} + if args.policy_config: + with open(args.policy_config, "r", encoding="utf-8") as f: + policy = json.load(f) + result = generator.generate_conditional_access_policy_script(policy) + elif args.task == "security-audit": + result = generator.generate_security_audit_script() + else: # bulk-license + if not (args.users_csv and args.license_sku): + parser.error("--users-csv and --license-sku are required for --task bulk-license") + result = generator.generate_bulk_license_assignment_script(args.users_csv, args.license_sku) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py b/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py index 1ffcd3a2..6523c1f8 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/tenant_setup.py @@ -445,3 +445,43 @@ Disconnect-MicrosoftTeams 'estimated_monthly_cost': round(estimated_monthly_cost, 2), 'estimated_annual_cost': round(estimated_monthly_cost * 12, 2) } + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate M365 tenant setup checklist, DNS records, license plan, and PowerShell setup script" + ) + parser.add_argument("--config", required=True, + help="Tenant config JSON file (top-level 'tenant_config' key or the config object itself)") + parser.add_argument("--format", choices=["json", "powershell"], default="json", + help="json = checklist + DNS + license plan; powershell = setup script") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + with open(args.config, "r", encoding="utf-8") as f: + data = json.load(f) + config = data.get("tenant_config", data) + manager = TenantSetupManager(config) + + if args.format == "powershell": + result = manager.generate_powershell_setup_script() + else: + result = json.dumps({ + "setup_checklist": manager.generate_setup_checklist(), + "dns_records": manager.generate_dns_records(), + "license_recommendations": manager.get_license_recommendations(), + }, indent=2) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py b/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py index 39864925..96577163 100644 --- a/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py +++ b/engineering-team/skills/ms365-tenant-manager/scripts/user_management.py @@ -445,3 +445,56 @@ Disconnect-ExchangeOnline -Confirm:$false 'errors': errors, 'warnings': warnings } + + +def main(): + """CLI entry point.""" + import argparse + import json + + parser = argparse.ArgumentParser( + description="Generate M365 user lifecycle PowerShell scripts and license/group recommendations" + ) + parser.add_argument("--domain", required=True, help="Primary tenant domain (e.g. acme.com)") + parser.add_argument("--action", required=True, choices=["create", "offboard", "validate", "recommend"], + help="create = bulk user creation script; offboard = offboarding script; " + "validate = check user data; recommend = license + group recommendations") + parser.add_argument("--users", help="Users JSON file (list of user objects) for create/validate/recommend") + parser.add_argument("--user-email", help="User email for offboard action") + parser.add_argument("--output", "-o", help="Output file (default: stdout)") + args = parser.parse_args() + + manager = UserLifecycleManager(args.domain) + + if args.action == "offboard": + if not args.user_email: + parser.error("--user-email is required for --action offboard") + result = manager.generate_user_offboarding_script(args.user_email) + else: + if not args.users: + parser.error("--users is required for this action") + with open(args.users, "r", encoding="utf-8") as f: + users = json.load(f) + if isinstance(users, dict): + users = users.get("users", [users]) + if args.action == "create": + result = manager.generate_user_creation_script(users) + elif args.action == "validate": + result = json.dumps([manager.validate_user_data(u) for u in users], indent=2) + else: # recommend + result = json.dumps([{ + "user": u.get("email", u.get("first_name", "unknown")), + "licenses": manager.generate_license_assignment_recommendations( + u.get("role", "staff"), u.get("department", "general")), + "groups": manager.generate_group_membership_recommendations(u), + } for u in users], indent=2) + + if args.output: + with open(args.output, "w", encoding="utf-8") as f: + f.write(result) + else: + print(result) + + +if __name__ == "__main__": + main() diff --git a/engineering-team/skills/senior-data-scientist/SKILL.md b/engineering-team/skills/senior-data-scientist/SKILL.md index 72c3b157..78e39a09 100644 --- a/engineering-team/skills/senior-data-scientist/SKILL.md +++ b/engineering-team/skills/senior-data-scientist/SKILL.md @@ -208,16 +208,10 @@ def diff_in_diff(df, outcome, treatment_col, post_col, controls=None): python -m pytest tests/ -v --cov=src/ python -m black src/ && python -m pylint src/ -# Training & evaluation -python scripts/train.py --config prod.yaml -python scripts/evaluate.py --model best.pth - -# Deployment -docker build -t service:v1 . -kubectl apply -f k8s/ -helm upgrade service ./charts/ - -# Monitoring & health -kubectl logs -f deployment/service -python scripts/health_check.py +# Bundled pipeline scaffolds (stdlib runners — extend the process() body with project logic) +python3 scripts/experiment_designer.py --input experiment_spec.json --output experiment_design.json +python3 scripts/feature_engineering_pipeline.py --input raw_features.json --output features.json +python3 scripts/model_evaluation_suite.py --input model_predictions.json --output evaluation.json +# Each prints a JSON run report ({status, processed_items, start/end_time}); any status other +# than "completed" means the stage failed — fix before moving to the next pipeline stage. ``` diff --git a/engineering-team/tdd-guide.zip b/engineering-team/tdd-guide.zip deleted file mode 100644 index 7c81c431..00000000 Binary files a/engineering-team/tdd-guide.zip and /dev/null differ diff --git a/engineering-team/tech-stack-evaluator.zip b/engineering-team/tech-stack-evaluator.zip deleted file mode 100644 index b7cbdc62..00000000 Binary files a/engineering-team/tech-stack-evaluator.zip and /dev/null differ diff --git a/engineering/.claude-plugin/plugin.json b/engineering/.claude-plugin/plugin.json index e51ce900..8e1f38a1 100644 --- a/engineering/.claude-plugin/plugin.json +++ b/engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "engineering-advanced-skills", - "description": "40 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, focused-fix, browser-automation, spec-driven-workflow, secrets-vault-manager, sql-database-assistant, self-eval, llm-cost-optimizer, prompt-governance, llm-wiki (second brain for Obsidian + Claude Code, Karpathy pattern), tc-tracker (task context tracker with lifecycle and handoff format), feature-flags-architect, kubernetes-operator, chaos-engineering, ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and more. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "37 advanced engineering skills: agent designer, agent workflow designer, RAG architect, database designer + schema designer + SQL assistant, migration architect, observability designer, dependency auditor, changelog generator (with semantic version bumper and hotfix/rollback procedures), API design reviewer, API test suite builder, CI/CD pipeline builder, MCP server builder, skill security auditor, skill tester, performance profiler, focused-fix, browser-automation, full-page-screenshot, git-worktree-manager, monorepo-navigator, codebase-onboarding, interview-system-designer, runbook-generator, spec-driven-workflow, secrets-vault-manager, env-secrets-manager, pr-review-expert, self-eval, tc-tracker (task context tracker with lifecycle and handoff format), feature-flags-architect, kubernetes-operator, chaos-engineering, ship-gate (pre-production 8-category audit with deploy-intent intercept), slo-architect (SLO designer, error-budget calculator with multi-window burn-rate alerts, SLO reviewer per Google SRE Workbook), and tech-debt-tracker. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", diff --git a/engineering/.codex/instructions.md b/engineering/.codex/instructions.md index faa51073..9d112692 100644 --- a/engineering/.codex/instructions.md +++ b/engineering/.codex/instructions.md @@ -19,7 +19,7 @@ When working on advanced engineering tasks, use the POWERFUL-tier skill system: | Performance tuning | performance-profiler | | API review | api-design-reviewer | | Monitoring/SLOs | observability-designer | -| Release management | release-manager | +| Release management / changelogs | changelog-generator | | Security audit | skill-security-auditor | | Tech debt | tech-debt-tracker | diff --git a/engineering/agenthub/skills/board/SKILL.md b/engineering/agenthub/skills/board/SKILL.md index 1ee54adf..483e7b15 100644 --- a/engineering/agenthub/skills/board/SKILL.md +++ b/engineering/agenthub/skills/board/SKILL.md @@ -1,6 +1,6 @@ --- name: "board" -description: "Read, write, and browse the AgentHub message board for agent coordination." +description: "Read, write, and browse the AgentHub message board for agent coordination. Use when the user runs /hub:board or asks to post, read, or inspect coordination messages between competing AgentHub agents." command: /hub:board --- diff --git a/engineering/agenthub/skills/eval/SKILL.md b/engineering/agenthub/skills/eval/SKILL.md index f1dc8c02..1eaf3c5d 100644 --- a/engineering/agenthub/skills/eval/SKILL.md +++ b/engineering/agenthub/skills/eval/SKILL.md @@ -1,6 +1,6 @@ --- name: "eval" -description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session." +description: "Evaluate and rank agent results by metric or LLM judge for an AgentHub session. Use when the user runs /hub:eval or asks to score, compare, or pick a winner among completed AgentHub agents." command: /hub:eval --- diff --git a/engineering/agenthub/skills/init/SKILL.md b/engineering/agenthub/skills/init/SKILL.md index 93a7505b..e013e2d6 100644 --- a/engineering/agenthub/skills/init/SKILL.md +++ b/engineering/agenthub/skills/init/SKILL.md @@ -1,6 +1,6 @@ --- name: "init" -description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria." +description: "Create a new AgentHub collaboration session with task, agent count, and evaluation criteria. Use when the user runs /hub:init or asks to start a multi-agent competition on a task." command: /hub:init --- diff --git a/engineering/agenthub/skills/merge/SKILL.md b/engineering/agenthub/skills/merge/SKILL.md index a4a3e6b6..104b7646 100644 --- a/engineering/agenthub/skills/merge/SKILL.md +++ b/engineering/agenthub/skills/merge/SKILL.md @@ -1,6 +1,6 @@ --- name: "merge" -description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees." +description: "Merge the winning agent's branch into base, archive losers, and clean up worktrees. Use when the user runs /hub:merge or asks to land the winning AgentHub result and tidy the session." command: /hub:merge --- diff --git a/engineering/agenthub/skills/run/SKILL.md b/engineering/agenthub/skills/run/SKILL.md index 1590c68d..4761879e 100644 --- a/engineering/agenthub/skills/run/SKILL.md +++ b/engineering/agenthub/skills/run/SKILL.md @@ -1,6 +1,6 @@ --- name: "run" -description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation." +description: "One-shot lifecycle command that chains init → baseline → spawn → eval → merge in a single invocation. Use when the user runs /hub:run or asks to execute a full AgentHub competition end-to-end." command: /hub:run --- diff --git a/engineering/agenthub/skills/spawn/SKILL.md b/engineering/agenthub/skills/spawn/SKILL.md index beb87b6e..4eb9a5a8 100644 --- a/engineering/agenthub/skills/spawn/SKILL.md +++ b/engineering/agenthub/skills/spawn/SKILL.md @@ -1,6 +1,6 @@ --- name: "spawn" -description: "Launch N parallel subagents in isolated git worktrees to compete on the session task." +description: "Launch N parallel subagents in isolated git worktrees to compete on the session task. Use when the user runs /hub:spawn or asks to start the competing agents for an initialized AgentHub session." command: /hub:spawn --- diff --git a/engineering/agenthub/skills/status/SKILL.md b/engineering/agenthub/skills/status/SKILL.md index ec5abf07..17f0ae7e 100644 --- a/engineering/agenthub/skills/status/SKILL.md +++ b/engineering/agenthub/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Show DAG state, agent progress, and branch status for an AgentHub session." +description: "Show DAG state, agent progress, and branch status for an AgentHub session. Use when the user runs /hub:status or asks how the AgentHub agents are doing." command: /hub:status --- diff --git a/engineering/autoresearch-agent/skills/loop/SKILL.md b/engineering/autoresearch-agent/skills/loop/SKILL.md index cd07d8b8..adbff858 100644 --- a/engineering/autoresearch-agent/skills/loop/SKILL.md +++ b/engineering/autoresearch-agent/skills/loop/SKILL.md @@ -1,6 +1,6 @@ --- name: "loop" -description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling." +description: "Start an autonomous experiment loop with user-selected interval (10min, 1h, daily, weekly, monthly). Uses CronCreate for scheduling. Use when the user runs /ar:loop or asks to run an autoresearch experiment continuously on a schedule." command: /ar:loop --- diff --git a/engineering/autoresearch-agent/skills/resume/SKILL.md b/engineering/autoresearch-agent/skills/resume/SKILL.md index 48bc7f79..2dd81260 100644 --- a/engineering/autoresearch-agent/skills/resume/SKILL.md +++ b/engineering/autoresearch-agent/skills/resume/SKILL.md @@ -1,6 +1,6 @@ --- name: "resume" -description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating." +description: "Resume a paused experiment. Checkout the experiment branch, read results history, continue iterating. Use when the user runs /ar:resume or asks to pick up a previously started autoresearch experiment." command: /ar:resume --- diff --git a/engineering/autoresearch-agent/skills/run/SKILL.md b/engineering/autoresearch-agent/skills/run/SKILL.md index 4a9caff1..1584d557 100644 --- a/engineering/autoresearch-agent/skills/run/SKILL.md +++ b/engineering/autoresearch-agent/skills/run/SKILL.md @@ -1,6 +1,6 @@ --- name: "run" -description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard." +description: "Run a single experiment iteration. Edit the target file, evaluate, keep or discard. Use when the user runs /ar:run or asks for one manual autoresearch iteration." command: /ar:run --- diff --git a/engineering/autoresearch-agent/skills/setup/SKILL.md b/engineering/autoresearch-agent/skills/setup/SKILL.md index 15d42d28..50b72766 100644 --- a/engineering/autoresearch-agent/skills/setup/SKILL.md +++ b/engineering/autoresearch-agent/skills/setup/SKILL.md @@ -1,6 +1,6 @@ --- name: "setup" -description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator." +description: "Set up a new autoresearch experiment interactively. Collects domain, target file, eval command, metric, direction, and evaluator. Use when the user runs /ar:setup or asks to start optimizing a file with the autoresearch loop." command: /ar:setup --- diff --git a/engineering/autoresearch-agent/skills/status/SKILL.md b/engineering/autoresearch-agent/skills/status/SKILL.md index 56b3ed4c..173737a8 100644 --- a/engineering/autoresearch-agent/skills/status/SKILL.md +++ b/engineering/autoresearch-agent/skills/status/SKILL.md @@ -1,6 +1,6 @@ --- name: "status" -description: "Show experiment dashboard with results, active loops, and progress." +description: "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going." command: /ar:status --- diff --git a/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md b/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md index 6d487ec9..57b49acd 100644 --- a/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md +++ b/engineering/data-quality-auditor/skills/data-quality-auditor/SKILL.md @@ -1,6 +1,6 @@ --- name: data-quality-auditor -description: Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. +description: Audit datasets for completeness, consistency, accuracy, and validity. Profile data distributions, detect anomalies and outliers, surface structural issues, and produce an actionable remediation plan. Use when the user asks to check data quality, profile a dataset, hunt outliers or missing values, or validate data before analysis or model training. --- You are an expert data quality engineer. Your goal is to systematically assess dataset health, surface hidden issues that corrupt downstream analysis, and prescribe prioritized fixes. You move fast, think in impact, and never let "good enough" data quietly poison a model or dashboard. diff --git a/engineering/skills/agent-designer/SKILL.md b/engineering/skills/agent-designer/SKILL.md index 6172cd02..d5f792f5 100644 --- a/engineering/skills/agent-designer/SKILL.md +++ b/engineering/skills/agent-designer/SKILL.md @@ -1,279 +1,76 @@ --- name: "agent-designer" -description: "Use when the user asks to design multi-agent systems, create agent architectures, define agent communication patterns, or build autonomous agent workflows." +description: "Use when the user asks to design a multi-agent system, pick an orchestration pattern (supervisor/swarm/pipeline), generate tool schemas for agents, or evaluate agent execution logs for cost, latency, and failure bottlenecks. Examples: 'design an agent architecture for research automation', 'generate Anthropic tool schemas from these tool descriptions', 'analyze these agent run logs for bottlenecks'. NOT for Claude Code workflow files (use workflow-builder) or single-agent prompt design (use agent-workflow-designer)." --- -# Agent Designer - Multi-Agent System Architecture +# Agent Designer — Multi-Agent System Architecture -**Tier:** POWERFUL -**Category:** Engineering -**Tags:** AI agents, architecture, system design, orchestration, multi-agent systems +Design, schema-generate, and evaluate multi-agent systems with three deterministic tools. The scripts are the workflow — do not freehand an architecture when the planner can score one from requirements. -## Overview +## When to use -Agent Designer is a comprehensive toolkit for designing, architecting, and evaluating multi-agent systems. It provides structured approaches to agent architecture patterns, tool design principles, communication strategies, and performance evaluation frameworks for building robust, scalable AI agent systems. +- Designing a new multi-agent system from requirements (pattern choice, roles, comms) +- Generating provider-ready tool schemas (Anthropic + OpenAI formats) from plain tool descriptions +- Evaluating execution logs: success rate, latency distribution, cost, bottlenecks -## Core Capabilities +**When NOT to use:** Claude Code Workflow-tool automations → `workflow-builder`; single-agent workflow scaffolds → `agent-workflow-designer`; multi-agent fan-out at runtime → `agenthub`. -### 1. Agent Architecture Patterns +## Pattern decision table -#### Single Agent Pattern -- **Use Case:** Simple, focused tasks with clear boundaries -- **Pros:** Minimal complexity, easy debugging, predictable behavior -- **Cons:** Limited scalability, single point of failure -- **Implementation:** Direct user-agent interaction with comprehensive tool access +| Choose | When | Watch out for | +|---|---|---| +| Single agent | One bounded task, < ~5 tools | Don't add agents you don't need | +| Supervisor | Central decomposition, specialists report back | Supervisor becomes the bottleneck | +| Pipeline | Strictly sequential stages with handoffs | Rigid order; slowest stage gates throughput | +| Hierarchical | Multiple org layers, > ~8 agents | Communication overhead per level | +| Swarm | Parallel peers, fault tolerance over predictability | Hard to debug; needs consensus rules | -#### Supervisor Pattern -- **Use Case:** Hierarchical task decomposition with centralized control -- **Architecture:** One supervisor agent coordinating multiple specialist agents -- **Pros:** Clear command structure, centralized decision making -- **Cons:** Supervisor bottleneck, complex coordination logic -- **Implementation:** Supervisor receives tasks, delegates to specialists, aggregates results +The planner applies this scoring deterministically — run it rather than picking by feel. -#### Swarm Pattern -- **Use Case:** Distributed problem solving with peer-to-peer collaboration -- **Architecture:** Multiple autonomous agents with shared objectives -- **Pros:** High parallelism, fault tolerance, emergent intelligence -- **Cons:** Complex coordination, potential conflicts, harder to predict -- **Implementation:** Agent discovery, consensus mechanisms, distributed task allocation +## Workflow -#### Hierarchical Pattern -- **Use Case:** Complex systems with multiple organizational layers -- **Architecture:** Tree structure with managers and workers at different levels -- **Pros:** Natural organizational mapping, clear responsibilities -- **Cons:** Communication overhead, potential bottlenecks at each level -- **Implementation:** Multi-level delegation with feedback loops +All paths relative to this skill folder. Each step's JSON output is the next step's design input. -#### Pipeline Pattern -- **Use Case:** Sequential processing with specialized stages -- **Architecture:** Agents arranged in processing pipeline -- **Pros:** Clear data flow, specialized optimization per stage -- **Cons:** Sequential bottlenecks, rigid processing order -- **Implementation:** Message queues between stages, state handoffs +### 1. Design the architecture -### 2. Agent Role Definition +Write a requirements JSON (copy `assets/sample_system_requirements.json` — keys: `goal`, `tasks[]`, `constraints{max_response_time, budget_per_task, concurrent_tasks}`, `team_size`): -#### Role Specification Framework -- **Identity:** Name, purpose statement, core competencies -- **Responsibilities:** Primary tasks, decision boundaries, success criteria -- **Capabilities:** Required tools, knowledge domains, processing limits -- **Interfaces:** Input/output formats, communication protocols -- **Constraints:** Security boundaries, resource limits, operational guidelines +```bash +python3 agent_planner.py requirements.json --format json -o arch +``` -#### Common Agent Archetypes +Emits `arch.json` with `architecture_design` (pattern, agents, communication links), `mermaid_diagram`, and `implementation_roadmap`. Read `architecture_design.pattern` and the per-agent role list; present the mermaid diagram to the user. -**Coordinator Agent** -- Orchestrates multi-agent workflows -- Makes high-level decisions and resource allocation -- Monitors system health and performance -- Handles escalations and conflict resolution +### 2. Generate tool schemas -**Specialist Agent** -- Deep expertise in specific domain (code, data, research) -- Optimized tools and knowledge for specialized tasks -- High-quality output within narrow scope -- Clear handoff protocols for out-of-scope requests +Describe each agent's tools in plain JSON (copy `assets/sample_tool_descriptions.json`), then: -**Interface Agent** -- Handles external interactions (users, APIs, systems) -- Protocol translation and format conversion -- Authentication and authorization management -- User experience optimization +```bash +python3 tool_schema_generator.py tool_descriptions.json --validate -o tools +``` -**Monitor Agent** -- System health monitoring and alerting -- Performance metrics collection and analysis -- Anomaly detection and reporting -- Compliance and audit trail maintenance +Emits `tools.json` (`tool_schemas`, `validation_summary`) plus provider-specific `tools_anthropic.json` / `tools_openai.json`. **Gate: every tool must print `✓ Valid`.** Fix any invalid schema before proceeding — never hand an agent an unvalidated schema. -### 3. Tool Design Principles +### 3. Evaluate execution logs -#### Schema Design -- **Input Validation:** Strong typing, required vs optional parameters -- **Output Consistency:** Standardized response formats, error handling -- **Documentation:** Clear descriptions, usage examples, edge cases -- **Versioning:** Backward compatibility, migration paths +Once the system runs (or against `assets/sample_execution_logs.json` for a dry run): -#### Error Handling Patterns -- **Graceful Degradation:** Partial functionality when dependencies fail -- **Retry Logic:** Exponential backoff, circuit breakers, max attempts -- **Error Propagation:** Structured error responses, error classification -- **Recovery Strategies:** Fallback methods, alternative approaches +```bash +python3 agent_evaluator.py execution_logs.json --detailed -o eval +``` -#### Idempotency Requirements -- **Safe Operations:** Read operations with no side effects -- **Idempotent Writes:** Same operation can be safely repeated -- **State Management:** Version tracking, conflict resolution -- **Atomicity:** All-or-nothing operation completion +Emits `eval.json` with `summary`, `agent_metrics`, `bottleneck_analysis`, `error_analysis`, `cost_breakdown`, `sla_compliance`, and `optimization_recommendations`, plus split files (`eval_errors.json`, `eval_recommendations.json`). -### 4. Communication Patterns +### 4. Verification loop -#### Message Passing -- **Asynchronous Messaging:** Decoupled agents, message queues -- **Message Format:** Structured payloads with metadata -- **Delivery Guarantees:** At-least-once, exactly-once semantics -- **Routing:** Direct messaging, publish-subscribe, broadcast +The design is not done until: -#### Shared State -- **State Stores:** Centralized data repositories -- **Consistency Models:** Strong, eventual, weak consistency -- **Access Patterns:** Read-heavy, write-heavy, mixed workloads -- **Conflict Resolution:** Last-writer-wins, merge strategies +1. `tool_schema_generator.py --validate` reports 0 invalid schemas. +2. `agent_evaluator.py` on a pilot run reports **0 critical issues** (the tool prints `CRITICAL: N critical issues` when found). If N > 0, apply the top item in `eval_recommendations.json`, re-run the pilot, and re-evaluate. +3. Compare your outputs against `expected_outputs/` to confirm the schema shape you're consuming hasn't drifted. -#### Event-Driven Architecture -- **Event Sourcing:** Immutable event logs, state reconstruction -- **Event Types:** Domain events, system events, integration events -- **Event Processing:** Real-time, batch, stream processing -- **Event Schema:** Versioned event formats, backward compatibility +## References -### 5. Guardrails and Safety - -#### Input Validation -- **Schema Enforcement:** Required fields, type checking, format validation -- **Content Filtering:** Harmful content detection, PII scrubbing -- **Rate Limiting:** Request throttling, resource quotas -- **Authentication:** Identity verification, authorization checks - -#### Output Filtering -- **Content Moderation:** Harmful content removal, quality checks -- **Consistency Validation:** Logic checks, constraint verification -- **Formatting:** Standardized output formats, clean presentation -- **Audit Logging:** Decision trails, compliance records - -#### Human-in-the-Loop -- **Approval Workflows:** Critical decision checkpoints -- **Escalation Triggers:** Confidence thresholds, risk assessment -- **Override Mechanisms:** Human judgment precedence -- **Feedback Loops:** Human corrections improve system behavior - -### 6. Evaluation Frameworks - -#### Task Completion Metrics -- **Success Rate:** Percentage of tasks completed successfully -- **Partial Completion:** Progress measurement for complex tasks -- **Task Classification:** Success criteria by task type -- **Failure Analysis:** Root cause identification and categorization - -#### Quality Assessment -- **Output Quality:** Accuracy, relevance, completeness measures -- **Consistency:** Response variability across similar inputs -- **Coherence:** Logical flow and internal consistency -- **User Satisfaction:** Feedback scores, usage patterns - -#### Cost Analysis -- **Token Usage:** Input/output token consumption per task -- **API Costs:** External service usage and charges -- **Compute Resources:** CPU, memory, storage utilization -- **Time-to-Value:** Cost per successful task completion - -#### Latency Distribution -- **Response Time:** End-to-end task completion time -- **Processing Stages:** Bottleneck identification per stage -- **Queue Times:** Wait times in processing pipelines -- **Resource Contention:** Impact of concurrent operations - -### 7. Orchestration Strategies - -#### Centralized Orchestration -- **Workflow Engine:** Central coordinator manages all agents -- **State Management:** Centralized workflow state tracking -- **Decision Logic:** Complex routing and branching rules -- **Monitoring:** Comprehensive visibility into all operations - -#### Decentralized Orchestration -- **Peer-to-Peer:** Agents coordinate directly with each other -- **Service Discovery:** Dynamic agent registration and lookup -- **Consensus Protocols:** Distributed decision making -- **Fault Tolerance:** No single point of failure - -#### Hybrid Approaches -- **Domain Boundaries:** Centralized within domains, federated across -- **Hierarchical Coordination:** Multiple orchestration levels -- **Context-Dependent:** Strategy selection based on task type -- **Load Balancing:** Distribute coordination responsibility - -### 8. Memory Patterns - -#### Short-Term Memory -- **Context Windows:** Working memory for current tasks -- **Session State:** Temporary data for ongoing interactions -- **Cache Management:** Performance optimization strategies -- **Memory Pressure:** Handling capacity constraints - -#### Long-Term Memory -- **Persistent Storage:** Durable data across sessions -- **Knowledge Base:** Accumulated domain knowledge -- **Experience Replay:** Learning from past interactions -- **Memory Consolidation:** Transferring from short to long-term - -#### Shared Memory -- **Collaborative Knowledge:** Shared learning across agents -- **Synchronization:** Consistency maintenance strategies -- **Access Control:** Permission-based memory access -- **Memory Partitioning:** Isolation between agent groups - -### 9. Scaling Considerations - -#### Horizontal Scaling -- **Agent Replication:** Multiple instances of same agent type -- **Load Distribution:** Request routing across agent instances -- **Resource Pooling:** Shared compute and storage resources -- **Geographic Distribution:** Multi-region deployments - -#### Vertical Scaling -- **Capability Enhancement:** More powerful individual agents -- **Tool Expansion:** Broader tool access per agent -- **Context Expansion:** Larger working memory capacity -- **Processing Power:** Higher throughput per agent - -#### Performance Optimization -- **Caching Strategies:** Response caching, tool result caching -- **Parallel Processing:** Concurrent task execution -- **Resource Optimization:** Efficient resource utilization -- **Bottleneck Elimination:** Systematic performance tuning - -### 10. Failure Handling - -#### Retry Mechanisms -- **Exponential Backoff:** Increasing delays between retries -- **Jitter:** Random delay variation to prevent thundering herd -- **Maximum Attempts:** Bounded retry behavior -- **Retry Conditions:** Transient vs permanent failure classification - -#### Fallback Strategies -- **Graceful Degradation:** Reduced functionality when systems fail -- **Alternative Approaches:** Different methods for same goals -- **Default Responses:** Safe fallback behaviors -- **User Communication:** Clear failure messaging - -#### Circuit Breakers -- **Failure Detection:** Monitoring failure rates and response times -- **State Management:** Open, closed, half-open circuit states -- **Recovery Testing:** Gradual return to normal operation -- **Cascading Failure Prevention:** Protecting upstream systems - -## Implementation Guidelines - -### Architecture Decision Process -1. **Requirements Analysis:** Understand system goals, constraints, scale -2. **Pattern Selection:** Choose appropriate architecture pattern -3. **Agent Design:** Define roles, responsibilities, interfaces -4. **Tool Architecture:** Design tool schemas and error handling -5. **Communication Design:** Select message patterns and protocols -6. **Safety Implementation:** Build guardrails and validation -7. **Evaluation Planning:** Define success metrics and monitoring -8. **Deployment Strategy:** Plan scaling and failure handling - -### Quality Assurance -- **Testing Strategy:** Unit, integration, and system testing approaches -- **Monitoring:** Real-time system health and performance tracking -- **Documentation:** Architecture documentation and runbooks -- **Security Review:** Threat modeling and security assessments - -### Continuous Improvement -- **Performance Monitoring:** Ongoing system performance analysis -- **User Feedback:** Incorporating user experience improvements -- **A/B Testing:** Controlled experiments for system improvements -- **Knowledge Base Updates:** Continuous learning and adaptation - -This skill provides the foundation for designing robust, scalable multi-agent systems that can handle complex tasks while maintaining safety, reliability, and performance at scale. \ No newline at end of file +- `references/agent_architecture_patterns.md` — pattern trade-offs in depth +- `references/tool_design_best_practices.md` — schema, idempotency, error-handling rules +- `references/evaluation_methodology.md` — metric definitions the evaluator implements diff --git a/engineering/skills/agent-designer/agent_evaluator.py b/engineering/skills/agent-designer/agent_evaluator.py index 709171c9..8d86c56a 100644 --- a/engineering/skills/agent-designer/agent_evaluator.py +++ b/engineering/skills/agent-designer/agent_evaluator.py @@ -777,6 +777,7 @@ class AgentEvaluator: "latency_reduction": min(0.5, (system_metrics.average_duration_ms - 5000) / system_metrics.average_duration_ms), "throughput_improvement": 1.5 }, + estimated_cost_savings=None, estimated_performance_gain=1.4, implementation_steps=[ "Profile and optimize slow operations", @@ -803,6 +804,7 @@ class AgentEvaluator: "reliability_improvement": 1.1 }, estimated_cost_savings=system_metrics.total_cost_usd * (error_analysis.percentage / 100) * 0.5, + estimated_performance_gain=None, implementation_steps=error_analysis.suggested_fixes, risks=["May require significant code changes"], prerequisites=["Root cause analysis", "Testing framework"] @@ -818,6 +820,7 @@ class AgentEvaluator: description=bottleneck.description, implementation_effort="medium", expected_impact=bottleneck.estimated_improvement, + estimated_cost_savings=None, estimated_performance_gain=list(bottleneck.estimated_improvement.values())[0] if bottleneck.estimated_improvement else 1.1, implementation_steps=bottleneck.optimization_suggestions, risks=["System downtime during implementation", "Potential cascade effects"], @@ -836,6 +839,7 @@ class AgentEvaluator: "throughput_improvement": 2.0, "scalability_headroom": 5.0 }, + estimated_cost_savings=None, estimated_performance_gain=2.0, implementation_steps=[ "Implement horizontal scaling for agents", diff --git a/engineering/skills/api-design-reviewer/SKILL.md b/engineering/skills/api-design-reviewer/SKILL.md index dba2ba62..94b8292c 100644 --- a/engineering/skills/api-design-reviewer/SKILL.md +++ b/engineering/skills/api-design-reviewer/SKILL.md @@ -13,6 +13,21 @@ description: "Comprehensive REST API design review with automated linting, break The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards. +## Quick Start — run the tools first + +```bash +# 1. Lint an OpenAPI/Swagger spec for convention violations +python3 scripts/api_linter.py openapi.json --format json -o lint.json + +# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking) +python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json + +# 3. Score overall design quality (gate: --min-grade fails below threshold) +python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json +``` + +Review flow: run all three, report linter findings + breaking changes + grade to the user, fix, then re-run until the linter is clean, `--exit-on-breaking` passes (or breaking changes are version-bumped), and the scorecard meets the agreed `--min-grade`. Never sign off an API review on prose alone — attach the tool outputs. + ## Core Capabilities ### 1. API Linting and Convention Analysis @@ -157,7 +172,7 @@ Accept: application/vnd.myapi.v1+json } ], "requestId": "req-123456", - "timestamp": "2024-02-16T13:00:00Z" + "timestamp": "2026-02-16T13:00:00Z" } } ``` @@ -414,8 +429,5 @@ fi 9. **Missing Rate Limiting**: Protect your API from abuse and overload 10. **Inadequate Testing**: Test all aspects including error cases and edge conditions -## Conclusion - -The API Design Reviewer skill provides a comprehensive framework for building, reviewing, and maintaining high-quality REST APIs. By following these guidelines and using the provided tools, development teams can create APIs that are consistent, well-documented, secure, and maintainable. Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle. \ No newline at end of file diff --git a/engineering/skills/changelog-generator/README.md b/engineering/skills/changelog-generator/README.md index 4b91dc25..7fd35eaa 100644 --- a/engineering/skills/changelog-generator/README.md +++ b/engineering/skills/changelog-generator/README.md @@ -20,12 +20,14 @@ python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict - - `scripts/generate_changelog.py`: parse commits, infer semver bump, render markdown/JSON, optional file prepend - `scripts/commit_linter.py`: validate commit subjects against Conventional Commits rules +- `scripts/version_bumper.py`: compute the recommended next version from `git log --oneline` output (`--current-version`, `--prerelease`, `--include-commands`) ## References - `references/ci-integration.md` - `references/changelog-formatting-guide.md` - `references/monorepo-strategy.md` +- `references/hotfix-procedures.md` (hotfix severity SLAs + rollback triggers, absorbed from the retired release-manager skill) ## Installation diff --git a/engineering/skills/changelog-generator/SKILL.md b/engineering/skills/changelog-generator/SKILL.md index 5d8c6e5f..f4bd75ff 100644 --- a/engineering/skills/changelog-generator/SKILL.md +++ b/engineering/skills/changelog-generator/SKILL.md @@ -1,6 +1,6 @@ --- name: "changelog-generator" -description: "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, or automating release notes in CI." +description: "Produce consistent, auditable release notes from Conventional Commits. Separates commit parsing, semantic-bump logic, and changelog rendering for automated releases with editorial control. Use when cutting a release, generating CHANGELOG.md from git history, computing the next semantic version from commits, automating release notes in CI, or planning a hotfix/rollback. Examples: 'generate the changelog for v1.4.0', 'what version bump do these commits require', 'we need an emergency hotfix process'." --- # Changelog Generator @@ -61,7 +61,18 @@ python3 scripts/generate_changelog.py \ --write CHANGELOG.md ``` -### 4. Lint Commits Before Merge +### 4. Compute the Next Version From Commits + +When the user has not decided the next version, derive it instead of guessing: + +```bash +git log v1.3.0..HEAD --oneline | \ + python3 scripts/version_bumper.py --current-version 1.3.0 --output-format json +``` + +Output JSON contains `recommended_version`, `bump_type` (`major`/`minor`/`patch`/`none`), and with `--include-commands` the exact `git tag` commands. Feed `recommended_version` into `generate_changelog.py --next-version`. Pre-releases: add `--prerelease alpha|beta|rc`. Input must be real `git log --oneline` output (hex hashes); a sample lives at `assets/sample_git_log.txt`. + +### 5. Lint Commits Before Merge ```bash python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text @@ -119,11 +130,38 @@ SemVer mapping: 5. Tag releases only after changelog generation succeeds. 6. Keep an `[Unreleased]` section for manual curation when needed. +## Hotfix Severity & SLAs + +When a release goes wrong, classify before acting (full procedures in [references/hotfix-procedures.md](references/hotfix-procedures.md)): + +| Severity | Definition | SLA | Approval | +|---|---|---|---| +| P0 — Critical | Outage, data loss, exploited vulnerability | Fix deployed ≤ 2h; emergency deploy bypasses normal gates | Engineering Lead + On-call Manager | +| P1 — High | Major feature broken, significant user impact | Fix deployed ≤ 24h; expedited review | Engineering Lead + Product Manager | +| P2 — Medium | Minor issues, limited impact | Next release cycle | Standard PR review | + +Hotfix branch comes from the last stable tag, contains the minimal fix only, and gets its own patch-bump changelog entry via the workflow above. + +## Rollback Triggers + +Pre-commit to these thresholds before tagging; roll back when any fires: + +| Trigger | Threshold | +|---|---| +| Error rate spike | > 2x baseline within 30 min | +| Performance degradation | > 50% latency increase | +| Feature failure | Core functionality broken | +| Security incident | Vulnerability being exploited | +| Data corruption | Database integrity compromised | + +Prefer feature-flag disable over code rollback; database rollbacks only for non-destructive migrations (forward-only migrations preferred). See [references/hotfix-procedures.md](references/hotfix-procedures.md). + ## References - [references/ci-integration.md](references/ci-integration.md) - [references/changelog-formatting-guide.md](references/changelog-formatting-guide.md) - [references/monorepo-strategy.md](references/monorepo-strategy.md) +- [references/hotfix-procedures.md](references/hotfix-procedures.md) - [README.md](README.md) ## Release Governance diff --git a/engineering/skills/release-manager/assets/sample_git_log.txt b/engineering/skills/changelog-generator/assets/sample_git_log.txt similarity index 100% rename from engineering/skills/release-manager/assets/sample_git_log.txt rename to engineering/skills/changelog-generator/assets/sample_git_log.txt diff --git a/engineering/skills/release-manager/references/hotfix-procedures.md b/engineering/skills/changelog-generator/references/hotfix-procedures.md similarity index 100% rename from engineering/skills/release-manager/references/hotfix-procedures.md rename to engineering/skills/changelog-generator/references/hotfix-procedures.md diff --git a/engineering/skills/release-manager/version_bumper.py b/engineering/skills/changelog-generator/scripts/version_bumper.py similarity index 100% rename from engineering/skills/release-manager/version_bumper.py rename to engineering/skills/changelog-generator/scripts/version_bumper.py diff --git a/engineering/skills/database-designer/SKILL.md b/engineering/skills/database-designer/SKILL.md index 9fa36ca8..ad2b94cf 100644 --- a/engineering/skills/database-designer/SKILL.md +++ b/engineering/skills/database-designer/SKILL.md @@ -33,6 +33,38 @@ A comprehensive database design skill that provides expert-level analysis, optim - **Rollback Strategy**: Complete reversal capabilities with validation - **Execution Planning**: Ordered migration steps with dependency resolution +## Tool Workflow (run these — do not analyze schemas by hand) + +All paths relative to this skill folder; sample inputs in `assets/`. + +### 1. Analyze the schema + +```bash +python3 schema_analyzer.py --input schema.sql --generate-erd --output-format json -o analysis.json +``` + +Accepts SQL DDL or JSON schema (`assets/sample_schema.sql` / `sample_schema.json`). Output includes normalization findings, missing constraints, naming issues, and a Mermaid ERD — show the ERD to the user and fix flagged issues before optimizing. + +### 2. Optimize indexes against real query patterns + +```bash +python3 index_optimizer.py --schema assets/sample_schema.json --queries assets/sample_query_patterns.json --analyze-existing --format json -o indexes.json +``` + +Write the user's hot queries into a query-patterns JSON first (copy `assets/sample_query_patterns.json`). Output is a priority-ordered list of CREATE INDEX recommendations plus redundant-index removals. + +### 3. Generate the migration + +```bash +python3 migration_generator.py --current current_schema.json --target target_schema.json --zero-downtime --format sql -o migration.sql +``` + +`--zero-downtime` emits an expand-contract plan; `--validate-only` checks feasibility without generating SQL. + +### 4. Verification loop + +Re-run step 1 on the *target* schema and assert the issues found in the first pass are gone; run `migration_generator.py --validate-only` before handing over the migration. + ## Database Design Principles → See references/database-design-reference.md for details @@ -280,10 +312,3 @@ Fixes: - **senior-backend** — application-layer patterns (connection pooling, ORM best practices) - **senior-devops** — infrastructure provisioning for database clusters and replicas ---- - -## Conclusion - -Effective database design requires balancing multiple competing concerns: performance, scalability, maintainability, and business requirements. This skill provides the tools and knowledge to make informed decisions throughout the database lifecycle, from initial schema design through production optimization and evolution. - -The included tools automate common analysis and optimization tasks, while the comprehensive guides provide the theoretical foundation for making sound architectural decisions. Whether building a new system or optimizing an existing one, these resources provide expert-level guidance for creating robust, scalable database solutions. diff --git a/engineering/skills/dependency-auditor/SKILL.md b/engineering/skills/dependency-auditor/SKILL.md index e118bbbd..c35daa0b 100644 --- a/engineering/skills/dependency-auditor/SKILL.md +++ b/engineering/skills/dependency-auditor/SKILL.md @@ -1,338 +1,85 @@ --- name: "dependency-auditor" -description: "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review." +description: "Audit and manage dependencies across multi-language projects. Identifies vulnerabilities, license conflicts, transitive dependency risks, and safe-upgrade paths. Use when auditing third-party packages before release, investigating a CVE, planning a major version bump, or running a license-compliance review. Examples: 'audit our npm dependencies', 'do we have GPL contamination', 'plan the upgrade to React 19'." --- # Dependency Auditor -> **Skill Type:** POWERFUL -> **Category:** Engineering -> **Domain:** Dependency Management & Security +> **Skill Type:** POWERFUL · **Category:** Engineering · **Domain:** Dependency Management & Security -## Overview - -The **Dependency Auditor** is a comprehensive toolkit for analyzing, auditing, and managing dependencies across multi-language software projects. This skill provides deep visibility into your project's dependency ecosystem, enabling teams to identify vulnerabilities, ensure license compliance, optimize dependency trees, and plan safe upgrades. - -In modern software development, dependencies form complex webs that can introduce significant security, legal, and maintenance risks. A single project might have hundreds of direct and transitive dependencies, each potentially introducing vulnerabilities, license conflicts, or maintenance burden. This skill addresses these challenges through automated analysis and actionable recommendations. - -## Core Capabilities - -### 1. Vulnerability Scanning & CVE Matching - -**Comprehensive Security Analysis** -- Scans dependencies against built-in vulnerability databases -- Matches Common Vulnerabilities and Exposures (CVE) patterns -- Identifies known security issues across multiple ecosystems -- Analyzes transitive dependency vulnerabilities -- Provides CVSS scores and exploit assessments -- Tracks vulnerability disclosure timelines -- Maps vulnerabilities to dependency paths - -**Multi-Language Support** -- **JavaScript/Node.js**: package.json, package-lock.json, yarn.lock -- **Python**: requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock -- **Go**: go.mod, go.sum -- **Rust**: Cargo.toml, Cargo.lock -- **Ruby**: Gemfile, Gemfile.lock -- **Java/Maven**: pom.xml, gradle.lockfile -- **PHP**: composer.json, composer.lock -- **C#/.NET**: packages.config, project.assets.json - -### 2. License Compliance & Legal Risk Assessment - -**License Classification System** -- **Permissive Licenses**: MIT, Apache 2.0, BSD (2-clause, 3-clause), ISC -- **Copyleft (Strong)**: GPL (v2, v3), AGPL (v3) -- **Copyleft (Weak)**: LGPL (v2.1, v3), MPL (v2.0) -- **Proprietary**: Commercial, custom, or restrictive licenses -- **Dual Licensed**: Multi-license scenarios and compatibility -- **Unknown/Ambiguous**: Missing or unclear licensing - -**Conflict Detection** -- Identifies incompatible license combinations -- Warns about GPL contamination in permissive projects -- Analyzes license inheritance through dependency chains -- Provides compliance recommendations for distribution -- Generates legal risk matrices for decision-making - -### 3. Outdated Dependency Detection - -**Version Analysis** -- Identifies dependencies with available updates -- Categorizes updates by severity (patch, minor, major) -- Detects pinned versions that may be outdated -- Analyzes semantic versioning patterns -- Identifies floating version specifiers -- Tracks release frequencies and maintenance status - -**Maintenance Status Assessment** -- Identifies abandoned or unmaintained packages -- Analyzes commit frequency and contributor activity -- Tracks last release dates and security patch availability -- Identifies packages with known end-of-life dates -- Assesses upstream maintenance quality - -### 4. Dependency Bloat Analysis - -**Unused Dependency Detection** -- Identifies dependencies that aren't actually imported/used -- Analyzes import statements and usage patterns -- Detects redundant dependencies with overlapping functionality -- Identifies oversized packages for simple use cases -- Maps actual vs. declared dependency usage - -**Redundancy Analysis** -- Identifies multiple packages providing similar functionality -- Detects version conflicts in transitive dependencies -- Analyzes bundle size impact of dependencies -- Identifies opportunities for dependency consolidation -- Maps dependency overlap and duplication - -### 5. Upgrade Path Planning & Breaking Change Risk - -**Semantic Versioning Analysis** -- Analyzes semver patterns to predict breaking changes -- Identifies safe upgrade paths (patch/minor versions) -- Flags major version updates requiring attention -- Tracks breaking changes across dependency updates -- Provides rollback strategies for failed upgrades - -**Risk Assessment Matrix** -- Low Risk: Patch updates, security fixes -- Medium Risk: Minor updates with new features -- High Risk: Major version updates, API changes -- Critical Risk: Dependencies with known breaking changes - -**Upgrade Prioritization** -- Security patches: Highest priority -- Bug fixes: High priority -- Feature updates: Medium priority -- Major rewrites: Planned priority -- Deprecated features: Immediate attention - -### 6. Supply Chain Security - -**Dependency Provenance** -- Verifies package signatures and checksums -- Analyzes package download sources and mirrors -- Identifies suspicious or compromised packages -- Tracks package ownership changes and maintainer shifts -- Detects typosquatting and malicious packages - -**Transitive Risk Analysis** -- Maps complete dependency trees -- Identifies high-risk transitive dependencies -- Analyzes dependency depth and complexity -- Tracks influence of indirect dependencies -- Provides supply chain risk scoring - -### 7. Lockfile Analysis & Deterministic Builds - -**Lockfile Validation** -- Ensures lockfiles are up-to-date with manifests -- Validates integrity hashes and version consistency -- Identifies drift between environments -- Analyzes lockfile conflicts and resolution strategies -- Ensures deterministic, reproducible builds - -**Environment Consistency** -- Compares dependencies across environments (dev/staging/prod) -- Identifies version mismatches between team members -- Validates CI/CD environment consistency -- Tracks dependency resolution differences - -## Technical Architecture - -### Scanner Engine (`dep_scanner.py`) -- Multi-format parser supporting 8+ package ecosystems -- Built-in vulnerability database with 500+ CVE patterns -- Transitive dependency resolution from lockfiles -- JSON and human-readable output formats -- Configurable scanning depth and exclusion patterns - -### License Analyzer (`license_checker.py`) -- License detection from package metadata and files -- Compatibility matrix with 20+ license types -- Conflict detection engine with remediation suggestions -- Risk scoring based on distribution and usage context -- Export capabilities for legal review - -### Upgrade Planner (`upgrade_planner.py`) -- Semantic version analysis with breaking change prediction -- Dependency ordering based on risk and interdependence -- Migration checklists with testing recommendations -- Rollback procedures for failed upgrades -- Timeline estimation for upgrade cycles - -## Use Cases & Applications - -### Security Teams -- **Vulnerability Management**: Continuous scanning for security issues -- **Incident Response**: Rapid assessment of vulnerable dependencies -- **Supply Chain Monitoring**: Tracking third-party security posture -- **Compliance Reporting**: Automated security compliance documentation - -### Legal & Compliance Teams -- **License Auditing**: Comprehensive license compliance verification -- **Risk Assessment**: Legal risk analysis for software distribution -- **Due Diligence**: Dependency licensing for M&A activities -- **Policy Enforcement**: Automated license policy compliance - -### Development Teams -- **Dependency Hygiene**: Regular cleanup of unused dependencies -- **Upgrade Planning**: Strategic dependency update scheduling -- **Performance Optimization**: Bundle size optimization through dep analysis -- **Technical Debt**: Identifying and prioritizing dependency technical debt - -### DevOps & Platform Teams -- **Build Optimization**: Faster builds through dependency optimization -- **Security Automation**: Automated vulnerability scanning in CI/CD -- **Environment Consistency**: Ensuring consistent dependencies across environments -- **Release Management**: Dependency-aware release planning - -## Integration Patterns - -### CI/CD Pipeline Integration -```bash -# Security gate in CI -python dep_scanner.py /project --format json --fail-on-high -python license_checker.py /project --policy strict --format json -``` - -### Scheduled Audits -```bash -# Weekly dependency audit -./audit_dependencies.sh > weekly_report.html -python upgrade_planner.py deps.json --timeline 30days -``` - -### Development Workflow -```bash -# Pre-commit dependency check -python dep_scanner.py . --quick-scan -python license_checker.py . --warn-conflicts -``` - -## Advanced Features - -### Custom Vulnerability Databases -- Support for internal/proprietary vulnerability feeds -- Custom CVE pattern definitions -- Organization-specific risk scoring -- Integration with enterprise security tools - -### Policy-Based Scanning -- Configurable license policies by project type -- Custom risk thresholds and escalation rules -- Automated policy enforcement and notifications -- Exception management for approved violations - -### Reporting & Dashboards -- Executive summaries for management -- Technical reports for development teams -- Trend analysis and dependency health metrics -- Integration with project management tools - -### Multi-Project Analysis -- Portfolio-level dependency analysis -- Shared dependency impact analysis -- Organization-wide license compliance -- Cross-project vulnerability propagation - -## Best Practices - -### Scanning Frequency -- **Security Scans**: Daily or on every commit -- **License Audits**: Weekly or monthly -- **Upgrade Planning**: Monthly or quarterly -- **Full Dependency Audit**: Quarterly - -### Risk Management -1. **Prioritize Security**: Address high/critical CVEs immediately -2. **License First**: Ensure compliance before functionality -3. **Gradual Updates**: Incremental dependency updates -4. **Test Thoroughly**: Comprehensive testing after updates -5. **Monitor Continuously**: Automated monitoring and alerting - -### Team Workflows -1. **Security Champions**: Designate dependency security owners -2. **Review Process**: Mandatory review for new dependencies -3. **Update Cycles**: Regular, scheduled dependency updates -4. **Documentation**: Maintain dependency rationale and decisions -5. **Training**: Regular team education on dependency security - -## Metrics & KPIs - -### Security Metrics -- Mean Time to Patch (MTTP) for vulnerabilities -- Number of high/critical vulnerabilities -- Percentage of dependencies with known vulnerabilities -- Security debt accumulation rate - -### Compliance Metrics -- License compliance percentage -- Number of license conflicts -- Time to resolve compliance issues -- Policy violation frequency - -### Maintenance Metrics -- Percentage of up-to-date dependencies -- Average dependency age -- Number of abandoned dependencies -- Upgrade success rate - -### Efficiency Metrics -- Bundle size reduction percentage -- Unused dependency elimination rate -- Build time improvement -- Developer productivity impact - -## Troubleshooting Guide - -### Common Issues -1. **False Positives**: Tuning vulnerability detection sensitivity -2. **License Ambiguity**: Resolving unclear or multiple licenses -3. **Breaking Changes**: Managing major version upgrades -4. **Performance Impact**: Optimizing scanning for large codebases - -### Resolution Strategies -- Whitelist false positives with documentation -- Contact maintainers for license clarification -- Implement feature flags for risky upgrades -- Use incremental scanning for large projects - -## Future Enhancements - -### Planned Features -- Machine learning for vulnerability prediction -- Automated dependency update pull requests -- Integration with container image scanning -- Real-time dependency monitoring dashboards -- Natural language policy definition - -### Ecosystem Expansion -- Additional language support (Swift, Kotlin, Dart) -- Container and infrastructure dependencies -- Development tool and build system dependencies -- Cloud service and SaaS dependency tracking - ---- +Offline, deterministic dependency auditing across 8+ package ecosystems. The three scripts are pattern-matchers over manifests/lockfiles — they do **not** call live advisory APIs; pair their findings with `npm audit` / `pip-audit` / `cargo audit` for current CVE coverage. ## Quick Start ```bash -# Scan project for vulnerabilities and licenses -python scripts/dep_scanner.py /path/to/project +# 1. Scan for vulnerabilities (built-in offline CVE pattern set; exit non-zero on high severity) +python3 scripts/dep_scanner.py /path/to/project --format json --fail-on-high -o scan.json -# Check license compliance -python scripts/license_checker.py /path/to/project --policy strict +# 2. Check license compliance and conflicts +python3 scripts/license_checker.py /path/to/project --policy strict --format json -o licenses.json -# Plan dependency upgrades -python scripts/upgrade_planner.py deps.json --risk-threshold medium +# 3. Plan upgrades from the scanner's inventory +python3 scripts/upgrade_planner.py scan.json --risk-threshold medium --timeline 90 --format json -o plan.json ``` -For detailed usage instructions, see [README.md](README.md). +Consume the outputs: `scan.json` findings drive which packages to pin/patch now; `licenses.json` conflicts go to the user as a legal-risk list; `plan.json` orders upgrades by risk with rollback notes. `--quick-scan` skips transitive deps; `--security-only` limits the plan to security fixes. ---- +**Verification loop:** after applying upgrades, re-run step 1 and assert 0 high-severity findings before closing the audit. -*This skill provides comprehensive dependency management capabilities essential for maintaining secure, compliant, and efficient software projects. Regular use helps teams stay ahead of security threats, maintain legal compliance, and optimize their dependency ecosystems.* \ No newline at end of file +## Supported Ecosystems + +| Language | Manifests parsed | +|---|---| +| JavaScript/Node | package.json, package-lock.json, yarn.lock | +| Python | requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock | +| Go | go.mod, go.sum | +| Rust | Cargo.toml, Cargo.lock | +| Ruby | Gemfile, Gemfile.lock | +| Java | pom.xml, gradle.lockfile | +| PHP | composer.json, composer.lock | +| C#/.NET | packages.config, project.assets.json | + +## License Classification + +- **Permissive**: MIT, Apache 2.0, BSD (2/3-clause), ISC +- **Copyleft (strong)**: GPL v2/v3, AGPL v3 — flags contamination risk in permissive projects +- **Copyleft (weak)**: LGPL v2.1/v3, MPL 2.0 +- **Proprietary / Dual / Unknown** — unknown licenses are surfaced for manual review + +The checker analyzes license inheritance through dependency chains and emits conflict pairs with remediation suggestions. + +## Upgrade Risk Matrix + +| Risk | Update type | Handling | +|---|---|---| +| Low | Patch, security fixes | Apply immediately | +| Medium | Minor with new features | Batch into scheduled update | +| High | Major version, API changes | Dedicated migration task + tests | +| Critical | Known breaking changes | Planned migration with rollback procedure | + +Prioritization: security patches > bug fixes > feature updates > major rewrites; deprecated features get immediate attention. + +## Scripts (accurate capability claims) + +- **`scripts/dep_scanner.py`** — multi-format parser; built-in offline vulnerability pattern set (~16 CVE patterns — a smoke layer, not a replacement for live advisories); transitive resolution from lockfiles; JSON + text output. +- **`scripts/license_checker.py`** — license detection from package metadata; compatibility matrix across 20+ license types; `--policy permissive|strict`; conflict detection with remediation. +- **`scripts/upgrade_planner.py`** — semver-based breaking-change prediction; risk-ordered migration plan with testing checklist and timeline estimation. + +Sample fixtures: `test-project/` and `test-inventory.json` in this folder; expected shapes in `expected_outputs/`. + +## CI Integration + +```bash +# Security gate in CI +python3 scripts/dep_scanner.py . --format json --fail-on-high +python3 scripts/license_checker.py . --policy strict --format json +``` + +## Best Practices + +1. **Prioritize security**: address high/critical findings immediately; license compliance before functionality. +2. **Gradual updates**: incremental upgrades with thorough testing; feature flags for risky bumps. +3. **Cadence**: security scans per commit; license audits monthly; full audit quarterly. +4. **False positives**: whitelist with documentation; contact maintainers for license ambiguity. + +See [README.md](README.md) for detailed usage and `references/` for the vulnerability/license knowledge bases. diff --git a/engineering/skills/engineering-advanced-skills/SKILL.md b/engineering/skills/engineering-advanced-skills/SKILL.md index e85e5178..9b405068 100644 --- a/engineering/skills/engineering-advanced-skills/SKILL.md +++ b/engineering/skills/engineering-advanced-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "engineering-advanced-skills" -description: "25 advanced engineering agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, release management, platform ops." +description: "Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -20,7 +20,7 @@ agents: # Engineering Advanced Skills (POWERFUL Tier) -25 advanced engineering skills for complex architecture, automation, and platform operations. +37 advanced engineering skills for complex architecture, automation, reliability, and platform operations. ## Quick Start @@ -38,31 +38,45 @@ npx agent-skills-cli add alirezarezvani/claude-skills/engineering | Skill | Folder | Focus | |-------|--------|-------| -| Agent Designer | `agent-designer/` | Multi-agent architecture patterns | -| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration | +| Agent Designer | `agent-designer/` | Multi-agent architecture: plan, schema-generate, evaluate | +| Agent Workflow Designer | `agent-workflow-designer/` | Workflow orchestration scaffolds | | API Design Reviewer | `api-design-reviewer/` | REST/GraphQL linting, breaking changes | | API Test Suite Builder | `api-test-suite-builder/` | API test generation | -| Changelog Generator | `changelog-generator/` | Automated changelogs | +| Browser Automation | `browser-automation/` | Playwright/Selenium automation patterns | +| Changelog Generator | `changelog-generator/` | Changelogs, semantic version bumps, hotfix/rollback discipline | +| Chaos Engineering | `chaos-engineering/` | Experiment design, blast-radius, postmortems | | CI/CD Pipeline Builder | `ci-cd-pipeline-builder/` | Pipeline generation | | Codebase Onboarding | `codebase-onboarding/` | New dev onboarding guides | -| Database Designer | `database-designer/` | Schema design, migrations | +| Database Designer | `database-designer/` | Schema analysis, index optimization, migrations | | Database Schema Designer | `database-schema-designer/` | ERD, normalization | | Dependency Auditor | `dependency-auditor/` | Dependency security scanning | | Env Secrets Manager | `env-secrets-manager/` | Secrets rotation, vault | +| Feature Flags Architect | `feature-flags-architect/` | Flag debt, rollout plans, kill switches | +| Focused Fix | `focused-fix/` | Systematic feature/module repair | +| Full Page Screenshot | `full-page-screenshot/` | Full-page capture tooling | | Git Worktree Manager | `git-worktree-manager/` | Parallel branch workflows | | Interview System Designer | `interview-system-designer/` | Hiring pipeline design | +| Kubernetes Operator | `kubernetes-operator/` | CRD validation, reconcile linting | | MCP Server Builder | `mcp-server-builder/` | MCP tool creation | | Migration Architect | `migration-architect/` | System migration planning | | Monorepo Navigator | `monorepo-navigator/` | Monorepo tooling | -| Observability Designer | `observability-designer/` | SLOs, alerts, dashboards | +| Observability Designer | `observability-designer/` | Dashboards, alert noise (SLOs → slo-architect) | | Performance Profiler | `performance-profiler/` | CPU, memory, load profiling | | PR Review Expert | `pr-review-expert/` | Pull request analysis | -| RAG Architect | `rag-architect/` | RAG system design | -| Release Manager | `release-manager/` | Release orchestration | +| RAG Architect | `rag-architect/` | RAG design, chunking, retrieval evaluation | | Runbook Generator | `runbook-generator/` | Operational runbooks | +| Secrets Vault Manager | `secrets-vault-manager/` | Vault patterns, HCL | +| Self-Eval | `self-eval/` | Honest work-quality scoring | +| Ship Gate | `ship-gate/` | Pre-production audit (89 checks) | | Skill Security Auditor | `skill-security-auditor/` | Skill vulnerability scanning | | Skill Tester | `skill-tester/` | Skill quality evaluation | -| Tech Debt Tracker | `tech-debt-tracker/` | Technical debt management | +| SLO Architect | `slo-architect/` | SLO/SLI design, error budgets, burn-rate alerts | +| Spec-Driven Workflow | `spec-driven-workflow/` | Spec-first development gates | +| SQL Database Assistant | `sql-database-assistant/` | Query optimization, 4 dialects | +| TC Tracker | `tc-tracker/` | Task context lifecycle + handoffs | +| Tech Debt Tracker | `tech-debt-tracker/` | Debt scan → prioritize → dashboard | + +Note: release management merged into `changelog-generator/` (version bumper + hotfix/rollback procedures live there now). ## Rules diff --git a/engineering/skills/migration-architect/SKILL.md b/engineering/skills/migration-architect/SKILL.md index c4adeafc..1bb65ecf 100644 --- a/engineering/skills/migration-architect/SKILL.md +++ b/engineering/skills/migration-architect/SKILL.md @@ -33,6 +33,25 @@ The Migration Architect skill provides comprehensive tools and methodologies for - **Service Rollback:** Plan service version rollbacks with traffic management - **Validation Checkpoints:** Define success criteria and rollback triggers +## Quick Start — plan → check compatibility → generate rollback + +All paths relative to this skill folder; sample inputs in `assets/`, expected shapes in `expected_outputs/`. + +```bash +# 1. Generate the migration plan from a spec (copy assets/sample_database_migration.json) +python3 scripts/migration_planner.py --input migration_spec.json --format json -o migration_plan.json + +# 2. Check schema/API compatibility — exits non-zero unless fully compatible (CI gate) +python3 scripts/compatibility_checker.py --before assets/database_schema_before.json --after assets/database_schema_after.json --type database --format json -o compatibility.json + +# 3. Generate the rollback runbook from the plan +python3 scripts/rollback_generator.py --input migration_plan.json --format both -o rollback_runbook +``` + +Outputs chain: `migration_plan.json` (`phases`, `risks`, `estimated_duration_hours`) feeds step 3; `compatibility.json` reports `overall_compatibility` plus `breaking_changes_count` / `potentially_breaking_count`. + +**Gate:** the migration is not approved until (a) `compatibility_checker` exits 0 (`overall_compatibility: compatible`) or every breaking/potentially-breaking item is explicitly accepted by the owner in writing, and (b) a rollback runbook exists for every phase in the plan. Re-run both checks after any schema revision. + ## Migration Patterns ### Database Migrations @@ -338,74 +357,6 @@ class MigrationCircuitBreaker: - [ ] Archive migration artifacts - [ ] Update disaster recovery procedures -## Communication Templates - -### Executive Summary Template -``` -Migration Status: [IN_PROGRESS | COMPLETED | ROLLED_BACK] -Start Time: [YYYY-MM-DD HH:MM UTC] -Current Phase: [X of Y] -Overall Progress: [X%] - -Key Metrics: -- System Availability: [X.XX%] -- Data Migration Progress: [X.XX%] -- Performance Impact: [+/-X%] -- Issues Encountered: [X] - -Next Steps: -1. [Action item 1] -2. [Action item 2] - -Risk Assessment: [LOW | MEDIUM | HIGH] -Rollback Status: [AVAILABLE | NOT_AVAILABLE] -``` - -### Technical Team Update Template -``` -Phase: [Phase Name] - [Status] -Duration: [Started] - [Expected End] - -Completed Tasks: -✓ [Task 1] -✓ [Task 2] - -In Progress: -🔄 [Task 3] - [X% complete] - -Upcoming: -⏳ [Task 4] - [Expected start time] - -Issues: -⚠️ [Issue description] - [Severity] - [ETA resolution] - -Metrics: -- Migration Rate: [X records/minute] -- Error Rate: [X.XX%] -- System Load: [CPU/Memory/Disk] -``` - -## Success Metrics - -### Technical Metrics -- **Migration Completion Rate:** Percentage of data/services successfully migrated -- **Downtime Duration:** Total system unavailability during migration -- **Data Consistency Score:** Percentage of data validation checks passing -- **Performance Delta:** Performance change compared to baseline -- **Error Rate:** Percentage of failed operations during migration - -### Business Metrics -- **Customer Impact Score:** Measure of customer experience degradation -- **Revenue Protection:** Percentage of revenue maintained during migration -- **Time to Value:** Duration from migration start to business value realization -- **Stakeholder Satisfaction:** Post-migration stakeholder feedback scores - -### Operational Metrics -- **Plan Adherence:** Percentage of migration executed according to plan -- **Issue Resolution Time:** Average time to resolve migration issues -- **Team Efficiency:** Resource utilization and productivity metrics -- **Knowledge Transfer Score:** Team readiness for post-migration operations - ## Tools and Technologies ### Migration Planning Tools diff --git a/engineering/skills/observability-designer/SKILL.md b/engineering/skills/observability-designer/SKILL.md index fe30b44d..8052ca2e 100644 --- a/engineering/skills/observability-designer/SKILL.md +++ b/engineering/skills/observability-designer/SKILL.md @@ -11,7 +11,26 @@ description: "Design production-ready observability strategies combining metrics ## Overview -Observability Designer enables you to create production-ready observability strategies that provide deep insights into system behavior, performance, and reliability. This skill combines the three pillars of observability (metrics, logs, traces) with proven frameworks like SLI/SLO design, golden signals monitoring, and alert optimization to create comprehensive observability solutions. +Observability Designer creates production-ready dashboards, alert configurations, and monitoring strategies across the three pillars (metrics, logs, traces). + +**When NOT to use → slo-architect.** For SLO/SLI design with error-budget math, multi-window burn-rate alerting thresholds, and SLO review gates, route to `slo-architect` — it is the authoritative skill for that half. This skill's `slo_designer.py` produces a quick scaffold only. This skill's lane: dashboards (`dashboard_generator.py`) and alert-noise reduction (`alert_optimizer.py`). + +## Quick Start + +```bash +# Dashboard spec (Grafana JSON + docs) for a service +python3 scripts/dashboard_generator.py --service-type api --name payments --criticality critical --role sre --format grafana -o dashboard.json --doc-output dashboard.md + +# Analyze an existing alert config for noise, duplicates, and coverage gaps +python3 scripts/alert_optimizer.py --input alerts.json --analyze-only --report alert_report.json +# ...then emit the optimized config once the report is reviewed: +python3 scripts/alert_optimizer.py --input alerts.json --output alerts_optimized.json + +# Quick SLO scaffold (hand off to slo-architect for the real error-budget work) +python3 scripts/slo_designer.py --service-type api --criticality high --user-facing true --service-name payments -o slo_scaffold.json +``` + +**Verification loop:** after deploying optimized alerts, track the report's noise metrics for one on-call rotation — if the actionable-alert ratio didn't improve, re-run `--analyze-only` against the live config and iterate. Import the generated dashboard into Grafana and confirm every golden-signal panel renders with live data before closing the task. ## Core Competencies @@ -251,19 +270,3 @@ Creates comprehensive dashboard specifications: - **Alert Tuning:** Ongoing alert threshold and routing optimization - **Dashboard Evolution:** User feedback-driven dashboard improvements - **Tool Evaluation:** Regular assessment of observability tool effectiveness - -## Success Metrics - -### Operational Metrics -- **Mean Time to Detection (MTTD):** How quickly issues are identified -- **Mean Time to Resolution (MTTR):** Time from detection to resolution -- **Alert Precision:** Percentage of actionable alerts -- **SLO Achievement:** Percentage of SLO targets met consistently - -### Business Metrics -- **System Reliability:** Overall uptime and user experience quality -- **Engineering Velocity:** Development team productivity and deployment frequency -- **Cost Efficiency:** Observability cost as percentage of infrastructure spend -- **Customer Satisfaction:** User-reported reliability and performance satisfaction - -This comprehensive observability design skill enables organizations to build robust, scalable monitoring and alerting systems that provide actionable insights while maintaining cost efficiency and operational excellence. \ No newline at end of file diff --git a/engineering/skills/rag-architect/SKILL.md b/engineering/skills/rag-architect/SKILL.md index b097fd77..20fdd61f 100644 --- a/engineering/skills/rag-architect/SKILL.md +++ b/engineering/skills/rag-architect/SKILL.md @@ -1,318 +1,71 @@ --- name: "rag-architect" -description: "Use when the user asks to design RAG pipelines, optimize retrieval strategies, choose embedding models, implement vector search, or build knowledge retrieval systems." +description: "Use when the user asks to design a RAG pipeline, choose a chunking strategy or embedding model, pick a vector database, or evaluate retrieval quality (precision@k, recall@k, NDCG). Examples: 'design a RAG system for our docs', 'what chunk size should I use for this corpus', 'evaluate my retriever against ground truth'. NOT for general LLM cost tuning (use llm-cost-optimizer) or agent loops over retrieval (use agenthub)." --- -# RAG Architect - POWERFUL +# RAG Architect -## Overview +Design, tune, and evaluate production RAG pipelines with three deterministic tools. Run the tools against the actual corpus and requirements — do not pick chunk sizes or databases by intuition. -The RAG (Retrieval-Augmented Generation) Architect skill provides comprehensive tools and knowledge for designing, implementing, and optimizing production-grade RAG pipelines. This skill covers the entire RAG ecosystem from document chunking strategies to evaluation frameworks, enabling you to build scalable, efficient, and accurate retrieval systems. +## Hard rules -## Core Competencies +1. **Never present model names or vendor prices as current facts.** Embedding models and vector-DB pricing rot in months. Recommend a *tier* (see table below), name a current-generation candidate, and tell the user to verify against the provider's live pricing page. +2. **Every design ends with an evaluation run.** A RAG design without `retrieval_evaluator.py` numbers is a hypothesis, not a deliverable. +3. **Chunking is corpus-driven.** Run `chunking_optimizer.py` on the real documents before choosing a strategy. -### 1. Document Processing & Chunking Strategies +## Embedding model tiers (pattern, not price list) -#### Fixed-Size Chunking -- **Character-based chunking**: Simple splitting by character count (e.g., 512, 1024, 2048 chars) -- **Token-based chunking**: Splitting by token count to respect model limits -- **Overlap strategies**: 10-20% overlap to maintain context continuity -- **Pros**: Predictable chunk sizes, simple implementation, consistent processing time -- **Cons**: May break semantic units, context boundaries ignored -- **Best for**: Uniform documents, when consistent chunk sizes are critical +| Tier | Current-generation examples (verify before use) | When | +|---|---|---| +| Fast / self-hosted | `all-MiniLM-L6-v2`, `bge-small` | Cost-sensitive, small scale, real-time | +| Balanced open | `all-mpnet-base-v2`, `bge-large`, `e5-large` | Quality without API dependency | +| Quality API | `text-embedding-3-large`, `voyage-3-large` | Accuracy-priority general retrieval | +| Code | `voyage-code-3`, CodeBERT-family | Code search corpora | -#### Sentence-Based Chunking -- **Sentence boundary detection**: Using NLTK, spaCy, or regex patterns -- **Sentence grouping**: Combining sentences until size threshold is reached -- **Paragraph preservation**: Avoiding mid-paragraph splits when possible -- **Pros**: Preserves natural language boundaries, better readability -- **Cons**: Variable chunk sizes, potential for very short/long chunks -- **Best for**: Narrative text, articles, books +**Pricing discipline:** build the cost model with a placeholder table — columns `model | $/1M tokens (verify) | dims | as-of date` — and have the user fill in live numbers. Same for vector DBs (Pinecone/Weaviate/Qdrant/Chroma/pgvector): the selection criteria (managed vs self-hosted, scale, filtering, existing Postgres) are durable; the dollar figures are not. -#### Paragraph-Based Chunking -- **Paragraph detection**: Double newlines, HTML tags, markdown formatting -- **Hierarchical splitting**: Respecting document structure (sections, subsections) -- **Size balancing**: Merging small paragraphs, splitting large ones -- **Pros**: Preserves logical document structure, maintains topic coherence -- **Cons**: Highly variable sizes, may create very large chunks -- **Best for**: Structured documents, technical documentation +## Workflow -#### Semantic Chunking -- **Topic modeling**: Using TF-IDF, embeddings similarity for topic detection -- **Heading-aware splitting**: Respecting document hierarchy (H1, H2, H3) -- **Content-based boundaries**: Detecting topic shifts using semantic similarity -- **Pros**: Maintains semantic coherence, respects document structure -- **Cons**: Complex implementation, computationally expensive -- **Best for**: Long-form content, technical manuals, research papers +All paths relative to this skill folder. Outputs chain: corpus analysis → design → evaluation. -#### Recursive Chunking -- **Hierarchical approach**: Try larger chunks first, recursively split if needed -- **Multi-level splitting**: Different strategies at different levels -- **Size optimization**: Minimize number of chunks while respecting size limits -- **Pros**: Optimal chunk utilization, preserves context when possible -- **Cons**: Complex logic, potential performance overhead -- **Best for**: Mixed content types, when chunk count optimization is important +### 1. Analyze the corpus and pick chunking -#### Document-Aware Chunking -- **File type detection**: PDF pages, Word sections, HTML elements -- **Metadata preservation**: Headers, footers, page numbers, sections -- **Table and image handling**: Special processing for non-text elements -- **Pros**: Preserves document structure and metadata -- **Cons**: Format-specific implementation required -- **Best for**: Multi-format document collections, when metadata is important +```bash +python3 chunking_optimizer.py /path/to/docs --extensions .md .txt -o chunking.json +``` -### 2. Embedding Model Selection +Emits `chunking.json` with `corpus_info`, per-strategy `strategy_results`, a `recommendation`, and `sample_chunks`. Use `recommendation.strategy` and its config; show the user 2-3 `sample_chunks` so they can sanity-check boundaries. -#### Dimension Considerations -- **128-256 dimensions**: Fast retrieval, lower memory usage, suitable for simple domains -- **512-768 dimensions**: Balanced performance, good for most applications -- **1024-1536 dimensions**: High quality, better for complex domains, higher cost -- **2048+ dimensions**: Maximum quality, specialized use cases, significant resources +### 2. Design the pipeline from requirements -#### Speed vs Quality Tradeoffs -- **Fast models**: sentence-transformers/all-MiniLM-L6-v2 (384 dim, ~14k tokens/sec) -- **Balanced models**: sentence-transformers/all-mpnet-base-v2 (768 dim, ~2.8k tokens/sec) -- **Quality models**: text-embedding-ada-002 (1536 dim, OpenAI API) -- **Specialized models**: Domain-specific fine-tuned models +Write a requirements JSON with these keys (all required): `document_types[]`, `document_count`, `avg_document_size` (chars), `queries_per_day`, `query_patterns[]`, `latency_requirement`, `budget_monthly`, `accuracy_priority` (0-1), `cost_priority` (0-1), `maintenance_complexity`. -#### Model Categories -- **General purpose**: all-MiniLM, all-mpnet, Universal Sentence Encoder -- **Code embeddings**: CodeBERT, GraphCodeBERT, CodeT5 -- **Scientific text**: SciBERT, BioBERT, ClinicalBERT -- **Multilingual**: LaBSE, multilingual-e5, paraphrase-multilingual +```bash +python3 rag_pipeline_designer.py requirements.json -o design.json +``` -### 3. Vector Database Selection +Emits `design.json` with `chunking`, `embedding`, `vector_db`, `retrieval`, `reranking`, `evaluation`, `total_cost`, `architecture_diagram` (mermaid), and `config_templates`. Present the diagram; label every `cost_monthly` figure as an estimate to verify (rule 1). -#### Pinecone -- **Managed service**: Fully hosted, auto-scaling -- **Features**: Metadata filtering, hybrid search, real-time updates -- **Pricing**: $70/month for 1M vectors (1536 dim), pay-per-use scaling -- **Best for**: Production applications, when managed service is preferred -- **Cons**: Vendor lock-in, costs can scale quickly +### 3. Evaluate retrieval quality -#### Weaviate -- **Open source**: Self-hosted or cloud options available -- **Features**: GraphQL API, multi-modal search, automatic vectorization -- **Scaling**: Horizontal scaling, HNSW indexing -- **Best for**: Complex data types, when GraphQL API is preferred -- **Cons**: Learning curve, requires infrastructure management +Prepare `queries.json` (list of `{id, text}` or `{"queries": [...]}`) and `ground_truth.json` (`{query_id: [relevant_doc_ids]}`), then: -#### Qdrant -- **Rust-based**: High performance, low memory footprint -- **Features**: Payload filtering, clustering, distributed deployment -- **API**: REST and gRPC interfaces -- **Best for**: High-performance requirements, resource-constrained environments -- **Cons**: Smaller community, fewer integrations +```bash +python3 retrieval_evaluator.py queries.json /path/to/docs ground_truth.json --k-values 3 5 10 -o eval.json +``` -#### Chroma -- **Embedded database**: SQLite-based, easy local development -- **Features**: Collections, metadata filtering, persistence -- **Scaling**: Limited, suitable for prototyping and small deployments -- **Best for**: Development, testing, small-scale applications -- **Cons**: Not suitable for production scale +Reports precision@k, recall@k, MRR, NDCG@k, plus `poor_precision_examples` / `poor_recall_examples` for failure analysis. -#### pgvector (PostgreSQL) -- **SQL integration**: Leverage existing PostgreSQL infrastructure -- **Features**: ACID compliance, joins with relational data, mature ecosystem -- **Performance**: ivfflat and HNSW indexing, parallel query processing -- **Best for**: When you already use PostgreSQL, need ACID compliance -- **Cons**: Requires PostgreSQL expertise, less specialized than purpose-built DBs +### 4. Verification loop -### 4. Retrieval Strategies +The design is done only when: -#### Dense Retrieval -- **Semantic similarity**: Using embedding cosine similarity -- **Advantages**: Captures semantic meaning, handles paraphrasing well -- **Limitations**: May miss exact keyword matches, requires good embeddings -- **Implementation**: Vector similarity search with k-NN or ANN algorithms +1. `eval.json` meets targets — typical floors: precision@5 ≥ 0.8, recall@10 ≥ 0.85 (set per use case with the user). +2. If below target: inspect the poor-example lists, then change **one** variable (chunking strategy → re-run step 1; embedding tier; add reranking; hybrid retrieval) and re-run step 3. Repeat. +3. Every recommended model/price in the deliverable carries a "verify current pricing/model availability" note with an as-of date. -#### Sparse Retrieval -- **Keyword-based**: TF-IDF, BM25, Elasticsearch -- **Advantages**: Exact keyword matching, interpretable results -- **Limitations**: Misses semantic similarity, vulnerable to vocabulary mismatch -- **Implementation**: Inverted indexes, term frequency analysis +## References -#### Hybrid Retrieval -- **Combination approach**: Dense + sparse retrieval with score fusion -- **Fusion strategies**: Reciprocal Rank Fusion (RRF), weighted combination -- **Benefits**: Combines semantic understanding with exact matching -- **Complexity**: Requires tuning fusion weights, more complex infrastructure - -#### Reranking -- **Two-stage approach**: Initial retrieval followed by reranking -- **Reranking models**: Cross-encoders, specialized reranking transformers -- **Benefits**: Higher precision, can use more sophisticated models for final ranking -- **Tradeoff**: Additional latency, computational cost - -### 5. Query Transformation Techniques - -#### HyDE (Hypothetical Document Embeddings) -- **Approach**: Generate hypothetical answer, embed answer instead of query -- **Benefits**: Improves retrieval by matching document style rather than query style -- **Implementation**: Use LLM to generate hypothetical document, embed that -- **Use cases**: When queries and documents have different styles - -#### Multi-Query Generation -- **Approach**: Generate multiple query variations, retrieve for each, merge results -- **Benefits**: Increases recall, handles query ambiguity -- **Implementation**: LLM generates 3-5 query variations, deduplicate results -- **Considerations**: Higher cost and latency due to multiple retrievals - -#### Step-Back Prompting -- **Approach**: Generate broader, more general version of specific query -- **Benefits**: Retrieves more general context that helps answer specific questions -- **Implementation**: Transform "What is the capital of France?" to "What are European capitals?" -- **Use cases**: When specific questions need general context - -### 6. Context Window Optimization - -#### Dynamic Context Assembly -- **Relevance-based ordering**: Most relevant chunks first -- **Diversity optimization**: Avoid redundant information -- **Token budget management**: Fit within model context limits -- **Hierarchical inclusion**: Include summaries before detailed chunks - -#### Context Compression -- **Summarization**: Compress less relevant chunks while preserving key information -- **Key information extraction**: Extract only relevant facts/entities -- **Template-based compression**: Use structured formats to reduce token usage -- **Selective inclusion**: Include only chunks above relevance threshold - -### 7. Evaluation Frameworks - -#### Faithfulness Metrics -- **Definition**: How well generated answers are grounded in retrieved context -- **Measurement**: Fact verification against source documents -- **Implementation**: NLI models to check entailment between answer and context -- **Threshold**: >90% for production systems - -#### Relevance Metrics -- **Context relevance**: How relevant retrieved chunks are to the query -- **Answer relevance**: How well the answer addresses the original question -- **Measurement**: Embedding similarity, human evaluation, LLM-as-judge -- **Targets**: Context relevance >0.8, Answer relevance >0.85 - -#### Context Precision & Recall -- **Precision@K**: Percentage of top-K results that are relevant -- **Recall@K**: Percentage of relevant documents found in top-K results -- **Mean Reciprocal Rank (MRR)**: Average of reciprocal ranks of first relevant result -- **NDCG@K**: Normalized Discounted Cumulative Gain at K - -#### End-to-End Metrics -- **RAGAS**: Comprehensive RAG evaluation framework -- **Correctness**: Factual accuracy of generated answers -- **Completeness**: Coverage of all relevant aspects -- **Consistency**: Consistency across multiple runs with same query - -### 8. Production Patterns - -#### Caching Strategies -- **Query-level caching**: Cache results for identical queries -- **Semantic caching**: Cache for semantically similar queries -- **Chunk-level caching**: Cache embedding computations -- **Multi-level caching**: Redis for hot queries, disk for warm queries - -#### Streaming Retrieval -- **Progressive loading**: Stream results as they become available -- **Incremental generation**: Generate answers while still retrieving -- **Real-time updates**: Handle document updates without full reprocessing -- **Connection management**: Handle client disconnections gracefully - -#### Fallback Mechanisms -- **Graceful degradation**: Fallback to simpler retrieval if primary fails -- **Cache fallbacks**: Serve stale results when retrieval is unavailable -- **Alternative sources**: Multiple vector databases for redundancy -- **Error handling**: Comprehensive error recovery and user communication - -### 9. Cost Optimization - -#### Embedding Cost Management -- **Batch processing**: Batch documents for embedding to reduce API costs -- **Caching strategies**: Cache embeddings to avoid recomputation -- **Model selection**: Balance cost vs quality for embedding models -- **Update optimization**: Only re-embed changed documents - -#### Vector Database Optimization -- **Index optimization**: Choose appropriate index types for use case -- **Compression**: Use quantization to reduce storage costs -- **Tiered storage**: Hot/warm/cold data strategies -- **Resource scaling**: Auto-scaling based on query patterns - -#### Query Optimization -- **Query routing**: Route simple queries to cheaper methods -- **Result caching**: Avoid repeated expensive retrievals -- **Batch querying**: Process multiple queries together when possible -- **Smart filtering**: Use metadata filters to reduce search space - -### 10. Guardrails & Safety - -#### Content Filtering -- **Toxicity detection**: Filter harmful or inappropriate content -- **PII detection**: Identify and handle personally identifiable information -- **Content validation**: Ensure retrieved content meets quality standards -- **Source verification**: Validate document authenticity and reliability - -#### Query Safety -- **Injection prevention**: Prevent malicious query injection attacks -- **Rate limiting**: Prevent abuse and ensure fair usage -- **Query validation**: Sanitize and validate user inputs -- **Access controls**: Ensure users can only access authorized content - -#### Response Safety -- **Hallucination detection**: Identify when model generates unsupported claims -- **Confidence scoring**: Provide confidence levels for generated responses -- **Source attribution**: Always provide sources for factual claims -- **Uncertainty handling**: Gracefully handle cases where answer is uncertain - -## Implementation Best Practices - -### Development Workflow -1. **Requirements gathering**: Understand use case, scale, and quality requirements -2. **Data analysis**: Analyze document corpus characteristics -3. **Prototype development**: Build minimal viable RAG pipeline -4. **Chunking optimization**: Test different chunking strategies -5. **Retrieval tuning**: Optimize retrieval parameters and thresholds -6. **Evaluation setup**: Implement comprehensive evaluation metrics -7. **Production deployment**: Scale-ready implementation with monitoring - -### Monitoring & Observability -- **Query analytics**: Track query patterns and performance -- **Retrieval metrics**: Monitor precision, recall, and latency -- **Generation quality**: Track faithfulness and relevance scores -- **System health**: Monitor database performance and availability -- **Cost tracking**: Monitor embedding and vector database costs - -### Maintenance & Updates -- **Document refresh**: Handle new documents and updates -- **Index maintenance**: Regular vector database optimization -- **Model updates**: Evaluate and migrate to improved models -- **Performance tuning**: Continuous optimization based on usage patterns -- **Security updates**: Regular security assessments and updates - -## Common Pitfalls & Solutions - -### Poor Chunking Strategy -- **Problem**: Chunks break mid-sentence or lose context -- **Solution**: Use boundary-aware chunking with overlap - -### Low Retrieval Precision -- **Problem**: Retrieved chunks are not relevant to query -- **Solution**: Improve embedding model, add reranking, tune similarity threshold - -### High Latency -- **Problem**: Slow retrieval and generation -- **Solution**: Optimize vector indexing, implement caching, use faster embedding models - -### Inconsistent Quality -- **Problem**: Variable answer quality across different queries -- **Solution**: Implement comprehensive evaluation, add quality scoring, improve fallbacks - -### Scalability Issues -- **Problem**: System doesn't scale with increased load -- **Solution**: Implement proper caching, database sharding, and auto-scaling - -## Conclusion - -Building effective RAG systems requires careful consideration of each component in the pipeline. The key to success is understanding the tradeoffs between different approaches and choosing the right combination of techniques for your specific use case. Start with simple approaches and gradually add sophistication based on evaluation results and production requirements. - -This skill provides the foundation for making informed decisions throughout the RAG development lifecycle, from initial design to production deployment and ongoing maintenance. \ No newline at end of file +- `references/chunking_strategies_comparison.md` — strategy trade-offs the optimizer implements +- `references/embedding_model_benchmark.md` — benchmark *methodology* (dated snapshot; staleness warning at top) +- `references/rag_evaluation_framework.md` — metric definitions (faithfulness, relevance, precision/recall/NDCG) diff --git a/engineering/skills/rag-architect/rag_pipeline_designer.py b/engineering/skills/rag-architect/rag_pipeline_designer.py index 3b4f096f..9fc73469 100644 --- a/engineering/skills/rag-architect/rag_pipeline_designer.py +++ b/engineering/skills/rag-architect/rag_pipeline_designer.py @@ -200,18 +200,18 @@ class RAGPipelineDesigner: if "code" in doc_types: if high_accuracy and not cost_sensitive: - model = "openai-code-search-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "voyage-code-3" + cost_per_1k_tokens = 0.00018 # verify current pricing before budgeting + dimensions = 1024 else: model = "sentence-transformers/code-bert-base" cost_per_1k_tokens = 0.0 # Self-hosted dimensions = 768 elif "scientific" in doc_types: if high_accuracy: - model = "openai-text-embedding-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "openai-text-embedding-3-large" + cost_per_1k_tokens = 0.00013 # verify current pricing before budgeting + dimensions = 3072 else: model = "sentence-transformers/scibert-nli" cost_per_1k_tokens = 0.0 @@ -222,9 +222,9 @@ class RAGPipelineDesigner: cost_per_1k_tokens = 0.0 dimensions = 384 elif high_accuracy: - model = "openai-text-embedding-ada-002" - cost_per_1k_tokens = 0.0001 - dimensions = 1536 + model = "openai-text-embedding-3-large" + cost_per_1k_tokens = 0.00013 # verify current pricing before budgeting + dimensions = 3072 else: model = "sentence-transformers/all-mpnet-base-v2" cost_per_1k_tokens = 0.0 @@ -443,9 +443,15 @@ graph TB def _load_embedding_models(self) -> Dict[str, Dict[str, Any]]: """Load embedding model specifications.""" return { - "openai-text-embedding-ada-002": { - "dimensions": 1536, - "cost_per_1k_tokens": 0.0001, + "openai-text-embedding-3-large": { + "dimensions": 3072, + "cost_per_1k_tokens": 0.00013, # verify current pricing + "quality": "high", + "speed": "medium" + }, + "voyage-3-large": { + "dimensions": 1024, + "cost_per_1k_tokens": 0.00018, # verify current pricing "quality": "high", "speed": "medium" }, diff --git a/engineering/skills/rag-architect/references/embedding_model_benchmark.md b/engineering/skills/rag-architect/references/embedding_model_benchmark.md index ff8e2b95..e6cb3dff 100644 --- a/engineering/skills/rag-architect/references/embedding_model_benchmark.md +++ b/engineering/skills/rag-architect/references/embedding_model_benchmark.md @@ -1,4 +1,6 @@ -# Embedding Model Benchmark 2024 +# Embedding Model Benchmark (historical snapshot, 2024) + +> **Staleness warning:** This benchmark is a dated snapshot. Model names, scores, and especially prices rot quickly — `text-embedding-ada-002` is legacy, and newer families (OpenAI `text-embedding-3-*`, Voyage `voyage-3` / `voyage-code-3`, Cohere `embed-v4`) have superseded several entries. Treat the *methodology* (dimensions vs. quality vs. cost trade-offs, NDCG@10 comparison protocol) as the durable content; verify current model IDs and per-token pricing against the providers' live pricing pages before recommending anything. ## Executive Summary diff --git a/engineering/skills/release-manager/README.md b/engineering/skills/release-manager/README.md deleted file mode 100644 index e9f9abca..00000000 --- a/engineering/skills/release-manager/README.md +++ /dev/null @@ -1,445 +0,0 @@ -# Release Manager - -A comprehensive release management toolkit for automating changelog generation, version bumping, and release planning based on conventional commits and industry best practices. - -## Overview - -The Release Manager skill provides three powerful Python scripts and comprehensive documentation for managing software releases: - -1. **changelog_generator.py** - Generate structured changelogs from git history -2. **version_bumper.py** - Determine correct semantic version bumps -3. **release_planner.py** - Assess release readiness and generate coordination plans - -## Quick Start - -### Prerequisites - -- Python 3.7+ -- Git repository with conventional commit messages -- No external dependencies required (uses only Python standard library) - -### Basic Usage - -```bash -# Generate changelog from recent commits -git log --oneline --since="1 month ago" | python changelog_generator.py - -# Determine version bump from commits since last tag -git log --oneline $(git describe --tags --abbrev=0)..HEAD | python version_bumper.py -c "1.2.3" - -# Assess release readiness -python release_planner.py --input assets/sample_release_plan.json -``` - -## Scripts Reference - -### changelog_generator.py - -Parses conventional commits and generates structured changelogs in multiple formats. - -**Input Options:** -- Git log text (oneline or full format) -- JSON array of commits -- Stdin or file input - -**Output Formats:** -- Markdown (Keep a Changelog format) -- JSON structured data -- Both with release statistics - -```bash -# From git log (recommended) -git log --oneline --since="last release" | python changelog_generator.py \ - --version "2.1.0" \ - --date "2024-01-15" \ - --base-url "https://github.com/yourorg/yourrepo" - -# From JSON file -python changelog_generator.py \ - --input assets/sample_commits.json \ - --input-format json \ - --format both \ - --summary - -# With custom output -git log --format="%h %s" v1.0.0..HEAD | python changelog_generator.py \ - --version "1.1.0" \ - --output CHANGELOG_DRAFT.md -``` - -**Features:** -- Parses conventional commit types (feat, fix, docs, etc.) -- Groups commits by changelog categories (Added, Fixed, Changed, etc.) -- Extracts issue references (#123, fixes #456) -- Identifies breaking changes -- Links to commits and PRs -- Generates release summary statistics - -### version_bumper.py - -Analyzes commits to determine semantic version bumps according to conventional commits. - -**Bump Rules:** -- **MAJOR:** Breaking changes (`feat!:` or `BREAKING CHANGE:`) -- **MINOR:** New features (`feat:`) -- **PATCH:** Bug fixes (`fix:`, `perf:`, `security:`) -- **NONE:** Documentation, tests, chores only - -```bash -# Basic version bump determination -git log --oneline v1.2.3..HEAD | python version_bumper.py --current-version "1.2.3" - -# With pre-release version -python version_bumper.py \ - --current-version "1.2.3" \ - --prerelease alpha \ - --input assets/sample_commits.json \ - --input-format json - -# Include bump commands and file updates -git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ - python version_bumper.py \ - --current-version "$(git describe --tags --abbrev=0)" \ - --include-commands \ - --include-files \ - --analysis -``` - -**Features:** -- Supports pre-release versions (alpha, beta, rc) -- Generates bump commands for npm, Python, Rust, Git -- Provides file update snippets -- Detailed commit analysis and categorization -- Custom rules for specific commit types -- JSON and text output formats - -### release_planner.py - -Assesses release readiness and generates comprehensive release coordination plans. - -**Input:** JSON release plan with features, quality gates, and stakeholders - -```bash -# Assess release readiness -python release_planner.py --input assets/sample_release_plan.json - -# Generate full release package -python release_planner.py \ - --input release_plan.json \ - --output-format markdown \ - --include-checklist \ - --include-communication \ - --include-rollback \ - --output release_report.md -``` - -**Features:** -- Feature readiness assessment with approval tracking -- Quality gate validation and reporting -- Stakeholder communication planning -- Rollback procedure generation -- Risk analysis and timeline assessment -- Customizable test coverage thresholds -- Multiple output formats (text, JSON, Markdown) - -## File Structure - -``` -release-manager/ -├── SKILL.md # Comprehensive methodology guide -├── README.md # This file -├── changelog_generator.py # Changelog generation script -├── version_bumper.py # Version bump determination -├── release_planner.py # Release readiness assessment -├── references/ # Reference documentation -│ ├── conventional-commits-guide.md # Conventional commits specification -│ ├── release-workflow-comparison.md # Git Flow vs GitHub Flow vs Trunk-based -│ └── hotfix-procedures.md # Emergency release procedures -├── assets/ # Sample data for testing -│ ├── sample_git_log.txt # Sample git log output -│ ├── sample_git_log_full.txt # Detailed git log format -│ ├── sample_commits.json # JSON commit data -│ └── sample_release_plan.json # Release plan template -└── expected_outputs/ # Example script outputs - ├── changelog_example.md # Expected changelog format - ├── version_bump_example.txt # Version bump output - └── release_readiness_example.txt # Release assessment report -``` - -## Integration Examples - -### CI/CD Pipeline Integration - -```yaml -# .github/workflows/release.yml -name: Automated Release -on: - push: - branches: [main] - -jobs: - release: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 # Need full history - - - name: Determine version bump - id: version - run: | - CURRENT=$(git describe --tags --abbrev=0) - git log --oneline $CURRENT..HEAD | \ - python scripts/version_bumper.py -c $CURRENT --output-format json > bump.json - echo "new_version=$(jq -r '.recommended_version' bump.json)" >> $GITHUB_OUTPUT - - - name: Generate changelog - run: | - git log --oneline ${{ steps.version.outputs.current_version }}..HEAD | \ - python scripts/changelog_generator.py \ - --version "${{ steps.version.outputs.new_version }}" \ - --base-url "https://github.com/${{ github.repository }}" \ - --output CHANGELOG_ENTRY.md - - - name: Create release - uses: actions/create-release@v1 - with: - tag_name: v${{ steps.version.outputs.new_version }} - release_name: Release ${{ steps.version.outputs.new_version }} - body_path: CHANGELOG_ENTRY.md -``` - -### Git Hooks Integration - -```bash -#!/bin/bash -# .git/hooks/pre-commit -# Validate conventional commit format - -commit_msg_file=$1 -commit_msg=$(cat $commit_msg_file) - -# Simple validation (more sophisticated validation available in commitlint) -if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf|ci|build)(\(.+\))?(!)?:"; then - echo "❌ Commit message doesn't follow conventional commits format" - echo "Expected: type(scope): description" - echo "Examples:" - echo " feat(auth): add OAuth2 integration" - echo " fix(api): resolve race condition" - echo " docs: update installation guide" - exit 1 -fi - -echo "✅ Commit message format is valid" -``` - -### Release Planning Automation - -```python -#!/usr/bin/env python3 -# generate_release_plan.py - Automatically generate release plans from project management tools - -import json -import requests -from datetime import datetime, timedelta - -def generate_release_plan_from_github(repo, milestone): - """Generate release plan from GitHub milestone and PRs.""" - - # Fetch milestone details - milestone_url = f"https://api.github.com/repos/{repo}/milestones/{milestone}" - milestone_data = requests.get(milestone_url).json() - - # Fetch associated issues/PRs - issues_url = f"https://api.github.com/repos/{repo}/issues?milestone={milestone}&state=all" - issues = requests.get(issues_url).json() - - release_plan = { - "release_name": milestone_data["title"], - "version": "TBD", # Fill in manually or extract from milestone - "target_date": milestone_data["due_on"], - "features": [] - } - - for issue in issues: - if issue.get("pull_request"): # It's a PR - feature = { - "id": f"GH-{issue['number']}", - "title": issue["title"], - "description": issue["body"][:200] + "..." if len(issue["body"]) > 200 else issue["body"], - "type": "feature", # Could be parsed from labels - "assignee": issue["assignee"]["login"] if issue["assignee"] else "", - "status": "ready" if issue["state"] == "closed" else "in_progress", - "pull_request_url": issue["pull_request"]["html_url"], - "issue_url": issue["html_url"], - "risk_level": "medium", # Could be parsed from labels - "qa_approved": "qa-approved" in [label["name"] for label in issue["labels"]], - "pm_approved": "pm-approved" in [label["name"] for label in issue["labels"]] - } - release_plan["features"].append(feature) - - return release_plan - -# Usage -if __name__ == "__main__": - plan = generate_release_plan_from_github("yourorg/yourrepo", "5") - with open("release_plan.json", "w") as f: - json.dump(plan, f, indent=2) - - print("Generated release_plan.json") - print("Run: python release_planner.py --input release_plan.json") -``` - -## Advanced Usage - -### Custom Commit Type Rules - -```bash -# Define custom rules for version bumping -python version_bumper.py \ - --current-version "1.2.3" \ - --custom-rules '{"security": "patch", "breaking": "major"}' \ - --ignore-types "docs,style,test" -``` - -### Multi-repository Release Coordination - -```bash -#!/bin/bash -# multi_repo_release.sh - Coordinate releases across multiple repositories - -repos=("frontend" "backend" "mobile" "docs") -base_version="2.1.0" - -for repo in "${repos[@]}"; do - echo "Processing $repo..." - cd "$repo" - - # Generate changelog for this repo - git log --oneline --since="1 month ago" | \ - python ../scripts/changelog_generator.py \ - --version "$base_version" \ - --output "CHANGELOG_$repo.md" - - # Determine version bump - git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ - python ../scripts/version_bumper.py \ - --current-version "$(git describe --tags --abbrev=0)" > "VERSION_$repo.txt" - - cd .. -done - -echo "Generated changelogs and version recommendations for all repositories" -``` - -### Integration with Slack/Teams - -```python -#!/usr/bin/env python3 -# notify_release_status.py - -import json -import requests -import subprocess - -def send_slack_notification(webhook_url, message): - payload = {"text": message} - requests.post(webhook_url, json=payload) - -def get_release_status(): - """Get current release status from release planner.""" - result = subprocess.run( - ["python", "release_planner.py", "--input", "release_plan.json", "--output-format", "json"], - capture_output=True, text=True - ) - return json.loads(result.stdout) - -# Usage in CI/CD -status = get_release_status() -if status["assessment"]["overall_status"] == "blocked": - message = f"🚫 Release {status['version']} is BLOCKED\n" - message += f"Issues: {', '.join(status['assessment']['blocking_issues'])}" - send_slack_notification(SLACK_WEBHOOK_URL, message) -elif status["assessment"]["overall_status"] == "ready": - message = f"✅ Release {status['version']} is READY for deployment!" - send_slack_notification(SLACK_WEBHOOK_URL, message) -``` - -## Best Practices - -### Commit Message Guidelines - -1. **Use conventional commits consistently** across your team -2. **Be specific** in commit descriptions: "fix: resolve race condition in user creation" vs "fix: bug" -3. **Reference issues** when applicable: "Closes #123" or "Fixes #456" -4. **Mark breaking changes** clearly with `!` or `BREAKING CHANGE:` footer -5. **Keep first line under 50 characters** when possible - -### Release Planning - -1. **Plan releases early** with clear feature lists and target dates -2. **Set quality gates** and stick to them (test coverage, security scans, etc.) -3. **Track approvals** from all relevant stakeholders -4. **Document rollback procedures** before deployment -5. **Communicate clearly** with both internal teams and external users - -### Version Management - -1. **Follow semantic versioning** strictly for predictable releases -2. **Use pre-release versions** for beta testing and gradual rollouts -3. **Tag releases consistently** with proper version numbers -4. **Maintain backwards compatibility** when possible to avoid major version bumps -5. **Document breaking changes** thoroughly with migration guides - -## Troubleshooting - -### Common Issues - -**"No valid commits found"** -- Ensure git log contains commit messages -- Check that commits follow conventional format -- Verify input format (git-log vs json) - -**"Invalid version format"** -- Use semantic versioning: 1.2.3, not 1.2 or v1.2.3.beta -- Pre-release format: 1.2.3-alpha.1 - -**"Missing required approvals"** -- Check feature risk levels in release plan -- High/critical risk features require additional approvals -- Update approval status in JSON file - -### Debug Mode - -All scripts support verbose output for debugging: - -```bash -# Add debug logging -python changelog_generator.py --input sample.txt --debug - -# Validate input data -python -c "import json; print(json.load(open('release_plan.json')))" - -# Test with sample data first -python release_planner.py --input assets/sample_release_plan.json -``` - -## Contributing - -When extending these scripts: - -1. **Maintain backwards compatibility** for existing command-line interfaces -2. **Add comprehensive tests** for new features -3. **Update documentation** including this README and SKILL.md -4. **Follow Python standards** (PEP 8, type hints where helpful) -5. **Use only standard library** to avoid dependencies - -## License - -This skill is part of the claude-skills repository and follows the same license terms. - ---- - -For detailed methodology and background information, see [SKILL.md](SKILL.md). -For specific workflow guidance, see the [references](references/) directory. -For testing the scripts, use the sample data in the [assets](assets/) directory. \ No newline at end of file diff --git a/engineering/skills/release-manager/SKILL.md b/engineering/skills/release-manager/SKILL.md deleted file mode 100644 index b48cd509..00000000 --- a/engineering/skills/release-manager/SKILL.md +++ /dev/null @@ -1,490 +0,0 @@ ---- -name: "release-manager" -description: "Use when the user asks to plan releases, manage changelogs, coordinate deployments, create release branches, or automate versioning." ---- - -# Release Manager - -**Tier:** POWERFUL -**Category:** Engineering -**Domain:** Software Release Management & DevOps - -## Overview - -The Release Manager skill provides comprehensive tools and knowledge for managing software releases end-to-end. From parsing conventional commits to generating changelogs, determining version bumps, and orchestrating release processes, this skill ensures reliable, predictable, and well-documented software releases. - -## Core Capabilities - -- **Automated Changelog Generation** from git history using conventional commits -- **Semantic Version Bumping** based on commit analysis and breaking changes -- **Release Readiness Assessment** with comprehensive checklists and validation -- **Release Planning & Coordination** with stakeholder communication templates -- **Rollback Planning** with automated recovery procedures -- **Hotfix Management** for emergency releases -- **Feature Flag Integration** for progressive rollouts - -## Key Components - -### Scripts - -1. **changelog_generator.py** - Parses git logs and generates structured changelogs -2. **version_bumper.py** - Determines correct version bumps from conventional commits -3. **release_planner.py** - Assesses release readiness and generates coordination plans - -### Documentation - -- Comprehensive release management methodology -- Conventional commits specification and examples -- Release workflow comparisons (Git Flow, Trunk-based, GitHub Flow) -- Hotfix procedures and emergency response protocols - -## Release Management Methodology - -### Semantic Versioning (SemVer) - -Semantic Versioning follows the MAJOR.MINOR.PATCH format where: - -- **MAJOR** version when you make incompatible API changes -- **MINOR** version when you add functionality in a backwards compatible manner -- **PATCH** version when you make backwards compatible bug fixes - -#### Pre-release Versions - -Pre-release versions are denoted by appending a hyphen and identifiers: -- `1.0.0-alpha.1` - Alpha releases for early testing -- `1.0.0-beta.2` - Beta releases for wider testing -- `1.0.0-rc.1` - Release candidates for final validation - -#### Version Precedence - -Version precedence is determined by comparing each identifier: -1. `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` -2. `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` -3. `1.0.0-rc.1` < `1.0.0` - -### Conventional Commits - -Conventional Commits provide a structured format for commit messages that enables automated tooling: - -#### Format -``` -[optional scope]: - -[optional body] - -[optional footer(s)] -``` - -#### Types -- **feat**: A new feature (correlates with MINOR version bump) -- **fix**: A bug fix (correlates with PATCH version bump) -- **docs**: Documentation only changes -- **style**: Changes that do not affect the meaning of the code -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **perf**: A code change that improves performance -- **test**: Adding missing tests or correcting existing tests -- **chore**: Changes to the build process or auxiliary tools -- **ci**: Changes to CI configuration files and scripts -- **build**: Changes that affect the build system or external dependencies -- **breaking**: Introduces a breaking change (correlates with MAJOR version bump) - -#### Examples -``` -feat(user-auth): add OAuth2 integration - -fix(api): resolve race condition in user creation - -docs(readme): update installation instructions - -feat!: remove deprecated payment API -BREAKING CHANGE: The legacy payment API has been removed -``` - -### Automated Changelog Generation - -Changelogs are automatically generated from conventional commits, organized by: - -#### Structure -```markdown -# Changelog - -## [Unreleased] -### Added -### Changed -### Deprecated -### Removed -### Fixed -### Security - -## [1.2.0] - 2024-01-15 -### Added -- OAuth2 authentication support (#123) -- User preference dashboard (#145) - -### Fixed -- Race condition in user creation (#134) -- Memory leak in image processing (#156) - -### Breaking Changes -- Removed legacy payment API -``` - -#### Grouping Rules -- **Added** for new features (feat) -- **Fixed** for bug fixes (fix) -- **Changed** for changes in existing functionality -- **Deprecated** for soon-to-be removed features -- **Removed** for now removed features -- **Security** for vulnerability fixes - -#### Metadata Extraction -- Link to pull requests and issues: `(#123)` -- Breaking changes highlighted prominently -- Scope-based grouping: `auth:`, `api:`, `ui:` -- Co-authored-by for contributor recognition - -### Version Bump Strategies - -Version bumps are determined by analyzing commits since the last release: - -#### Automatic Detection Rules -1. **MAJOR**: Any commit with `BREAKING CHANGE` or `!` after type -2. **MINOR**: Any `feat` type commits without breaking changes -3. **PATCH**: `fix`, `perf`, `security` type commits -4. **NO BUMP**: `docs`, `style`, `test`, `chore`, `ci`, `build` only - -#### Pre-release Handling -```python -# Alpha: 1.0.0-alpha.1 → 1.0.0-alpha.2 -# Beta: 1.0.0-alpha.5 → 1.0.0-beta.1 -# RC: 1.0.0-beta.3 → 1.0.0-rc.1 -# Release: 1.0.0-rc.2 → 1.0.0 -``` - -#### Multi-package Considerations -For monorepos with multiple packages: -- Analyze commits affecting each package independently -- Support scoped version bumps: `@scope/package@1.2.3` -- Generate coordinated release plans across packages - -### Release Branch Workflows - -#### Git Flow -``` -main (production) ← release/1.2.0 ← develop ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Clear separation of concerns -- Stable main branch -- Parallel feature development -- Structured release process - -**Process:** -1. Create release branch from develop: `git checkout -b release/1.2.0 develop` -2. Finalize release (version bump, changelog) -3. Merge to main and develop -4. Tag release: `git tag v1.2.0` -5. Deploy from main - -#### Trunk-based Development -``` -main ← feature/login (short-lived) - ← feature/payment (short-lived) - ← hotfix/critical-fix -``` - -**Advantages:** -- Simplified workflow -- Faster integration -- Reduced merge conflicts -- Continuous integration friendly - -**Process:** -1. Short-lived feature branches (1-3 days) -2. Frequent commits to main -3. Feature flags for incomplete features -4. Automated testing gates -5. Deploy from main with feature toggles - -#### GitHub Flow -``` -main ← feature/login - ← hotfix/critical-fix -``` - -**Advantages:** -- Simple and lightweight -- Fast deployment cycle -- Good for web applications -- Minimal overhead - -**Process:** -1. Create feature branch from main -2. Regular commits and pushes -3. Open pull request when ready -4. Deploy from feature branch for testing -5. Merge to main and deploy - -### Feature Flag Integration - -Feature flags enable safe, progressive rollouts: - -#### Types of Feature Flags -- **Release flags**: Control feature visibility in production -- **Experiment flags**: A/B testing and gradual rollouts -- **Operational flags**: Circuit breakers and performance toggles -- **Permission flags**: Role-based feature access - -#### Implementation Strategy -```python -# Progressive rollout example -if feature_flag("new_payment_flow", user_id): - return new_payment_processor.process(payment) -else: - return legacy_payment_processor.process(payment) -``` - -#### Release Coordination -1. Deploy code with feature behind flag (disabled) -2. Gradually enable for percentage of users -3. Monitor metrics and error rates -4. Full rollout or quick rollback based on data -5. Remove flag in subsequent release - -### Release Readiness Checklists - -#### Pre-Release Validation -- [ ] All planned features implemented and tested -- [ ] Breaking changes documented with migration guide -- [ ] API documentation updated -- [ ] Database migrations tested -- [ ] Security review completed for sensitive changes -- [ ] Performance testing passed thresholds -- [ ] Internationalization strings updated -- [ ] Third-party integrations validated - -#### Quality Gates -- [ ] Unit test coverage ≥ 85% -- [ ] Integration tests passing -- [ ] End-to-end tests passing -- [ ] Static analysis clean -- [ ] Security scan passed -- [ ] Dependency audit clean -- [ ] Load testing completed - -#### Documentation Requirements -- [ ] CHANGELOG.md updated -- [ ] README.md reflects new features -- [ ] API documentation generated -- [ ] Migration guide written for breaking changes -- [ ] Deployment notes prepared -- [ ] Rollback procedure documented - -#### Stakeholder Approvals -- [ ] Product Manager sign-off -- [ ] Engineering Lead approval -- [ ] QA validation complete -- [ ] Security team clearance -- [ ] Legal review (if applicable) -- [ ] Compliance check (if regulated) - -### Deployment Coordination - -#### Communication Plan -**Internal Stakeholders:** -- Engineering team: Technical changes and rollback procedures -- Product team: Feature descriptions and user impact -- Support team: Known issues and troubleshooting guides -- Sales team: Customer-facing changes and talking points - -**External Communication:** -- Release notes for users -- API changelog for developers -- Migration guide for breaking changes -- Downtime notifications if applicable - -#### Deployment Sequence -1. **Pre-deployment** (T-24h): Final validation, freeze code -2. **Database migrations** (T-2h): Run and validate schema changes -3. **Blue-green deployment** (T-0): Switch traffic gradually -4. **Post-deployment** (T+1h): Monitor metrics and logs -5. **Rollback window** (T+4h): Decision point for rollback - -#### Monitoring & Validation -- Application health checks -- Error rate monitoring -- Performance metrics tracking -- User experience monitoring -- Business metrics validation -- Third-party service integration health - -### Hotfix Procedures - -Hotfixes address critical production issues requiring immediate deployment: - -#### Severity Classification -**P0 - Critical**: Complete system outage, data loss, security breach -- **SLA**: Fix within 2 hours -- **Process**: Emergency deployment, all hands on deck -- **Approval**: Engineering Lead + On-call Manager - -**P1 - High**: Major feature broken, significant user impact -- **SLA**: Fix within 24 hours -- **Process**: Expedited review and deployment -- **Approval**: Engineering Lead + Product Manager - -**P2 - Medium**: Minor feature issues, limited user impact -- **SLA**: Fix in next release cycle -- **Process**: Normal review process -- **Approval**: Standard PR review - -#### Emergency Response Process -1. **Incident declaration**: Page on-call team -2. **Assessment**: Determine severity and impact -3. **Hotfix branch**: Create from last stable release -4. **Minimal fix**: Address root cause only -5. **Expedited testing**: Automated tests + manual validation -6. **Emergency deployment**: Deploy to production -7. **Post-incident**: Root cause analysis and prevention - -### Rollback Planning - -Every release must have a tested rollback plan: - -#### Rollback Triggers -- **Error rate spike**: >2x baseline within 30 minutes -- **Performance degradation**: >50% latency increase -- **Feature failures**: Core functionality broken -- **Security incident**: Vulnerability exploited -- **Data corruption**: Database integrity compromised - -#### Rollback Types -**Code Rollback:** -- Revert to previous Docker image -- Database-compatible code changes only -- Feature flag disable preferred over code rollback - -**Database Rollback:** -- Only for non-destructive migrations -- Data backup required before migration -- Forward-only migrations preferred (add columns, not drop) - -**Infrastructure Rollback:** -- Blue-green deployment switch -- Load balancer configuration revert -- DNS changes (longer propagation time) - -#### Automated Rollback -```python -# Example rollback automation -def monitor_deployment(): - if error_rate() > THRESHOLD: - alert_oncall("Error rate spike detected") - if auto_rollback_enabled(): - execute_rollback() -``` - -### Release Metrics & Analytics - -#### Key Performance Indicators -- **Lead Time**: From commit to production -- **Deployment Frequency**: Releases per week/month -- **Mean Time to Recovery**: From incident to resolution -- **Change Failure Rate**: Percentage of releases causing incidents - -#### Quality Metrics -- **Rollback Rate**: Percentage of releases rolled back -- **Hotfix Rate**: Hotfixes per regular release -- **Bug Escape Rate**: Production bugs per release -- **Time to Detection**: How quickly issues are identified - -#### Process Metrics -- **Review Time**: Time spent in code review -- **Testing Time**: Automated + manual testing duration -- **Approval Cycle**: Time from PR to merge -- **Release Preparation**: Time spent on release activities - -### Tool Integration - -#### Version Control Systems -- **Git**: Primary VCS with conventional commit parsing -- **GitHub/GitLab**: Pull request automation and CI/CD -- **Bitbucket**: Pipeline integration and deployment gates - -#### CI/CD Platforms -- **Jenkins**: Pipeline orchestration and deployment automation -- **GitHub Actions**: Workflow automation and release publishing -- **GitLab CI**: Integrated pipelines with environment management -- **CircleCI**: Container-based builds and deployments - -#### Monitoring & Alerting -- **DataDog**: Application performance monitoring -- **New Relic**: Error tracking and performance insights -- **Sentry**: Error aggregation and release tracking -- **PagerDuty**: Incident response and escalation - -#### Communication Platforms -- **Slack**: Release notifications and coordination -- **Microsoft Teams**: Stakeholder communication -- **Email**: External customer notifications -- **Status Pages**: Public incident communication - -## Best Practices - -### Release Planning -1. **Regular cadence**: Establish predictable release schedule -2. **Feature freeze**: Lock changes 48h before release -3. **Risk assessment**: Evaluate changes for potential impact -4. **Stakeholder alignment**: Ensure all teams are prepared - -### Quality Assurance -1. **Automated testing**: Comprehensive test coverage -2. **Staging environment**: Production-like testing environment -3. **Canary releases**: Gradual rollout to subset of users -4. **Monitoring**: Proactive issue detection - -### Communication -1. **Clear timelines**: Communicate schedules early -2. **Regular updates**: Status reports during release process -3. **Issue transparency**: Honest communication about problems -4. **Post-mortems**: Learn from incidents and improve - -### Automation -1. **Reduce manual steps**: Automate repetitive tasks -2. **Consistent process**: Same steps every time -3. **Audit trails**: Log all release activities -4. **Self-service**: Enable teams to deploy safely - -## Common Anti-patterns - -### Process Anti-patterns -- **Manual deployments**: Error-prone and inconsistent -- **Last-minute changes**: Risk introduction without proper testing -- **Skipping testing**: Deploying without validation -- **Poor communication**: Stakeholders unaware of changes - -### Technical Anti-patterns -- **Monolithic releases**: Large, infrequent releases with high risk -- **Coupled deployments**: Services that must be deployed together -- **No rollback plan**: Unable to quickly recover from issues -- **Environment drift**: Production differs from staging - -### Cultural Anti-patterns -- **Blame culture**: Fear of making changes or reporting issues -- **Hero culture**: Relying on individuals instead of process -- **Perfectionism**: Delaying releases for minor improvements -- **Risk aversion**: Avoiding necessary changes due to fear - -## Getting Started - -1. **Assessment**: Evaluate current release process and pain points -2. **Tool setup**: Configure scripts for your repository -3. **Process definition**: Choose appropriate workflow for your team -4. **Automation**: Implement CI/CD pipelines and quality gates -5. **Training**: Educate team on new processes and tools -6. **Monitoring**: Set up metrics and alerting for releases -7. **Iteration**: Continuously improve based on feedback and metrics - -The Release Manager skill transforms chaotic deployments into predictable, reliable releases that build confidence across your entire organization. \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_commits.json b/engineering/skills/release-manager/assets/sample_commits.json deleted file mode 100644 index 543a2b81..00000000 --- a/engineering/skills/release-manager/assets/sample_commits.json +++ /dev/null @@ -1,80 +0,0 @@ -[ - { - "hash": "a1b2c3d", - "author": "Sarah Johnson ", - "date": "2024-01-15T14:30:22Z", - "message": "feat(auth): add OAuth2 integration with Google and GitHub\n\nImplement OAuth2 authentication flow supporting Google and GitHub providers.\nUsers can now sign in using their existing social media accounts, improving\nuser experience and reducing password fatigue.\n\n- Add OAuth2 client configuration\n- Implement authorization code flow\n- Add user profile mapping from providers\n- Include comprehensive error handling\n\nCloses #123\nResolves #145" - }, - { - "hash": "e4f5g6h", - "author": "Mike Chen ", - "date": "2024-01-15T13:45:18Z", - "message": "fix(api): resolve race condition in user creation endpoint\n\nFixed a race condition that occurred when multiple requests attempted\nto create users with the same email address simultaneously. This was\ncausing duplicate user records in some edge cases.\n\n- Added database unique constraint on email field\n- Implemented proper error handling for constraint violations\n- Added retry logic with exponential backoff\n\nFixes #234" - }, - { - "hash": "i7j8k9l", - "author": "Emily Davis ", - "date": "2024-01-15T12:20:45Z", - "message": "docs(readme): update installation and deployment instructions\n\nUpdated README with comprehensive installation guide including:\n- Docker setup instructions\n- Environment variable configuration\n- Database migration steps\n- Troubleshooting common issues" - }, - { - "hash": "m1n2o3p", - "author": "David Wilson ", - "date": "2024-01-15T11:15:30Z", - "message": "feat(ui)!: redesign dashboard with new component library\n\nComplete redesign of the user dashboard using our new component library.\nThis provides better accessibility, improved mobile responsiveness, and\na more modern user interface.\n\nBREAKING CHANGE: The dashboard API endpoints have changed structure.\nFrontend clients must update to use the new /v2/dashboard endpoints.\nThe legacy /v1/dashboard endpoints will be removed in version 3.0.0.\n\n- Implement new Card, Grid, and Chart components\n- Add responsive breakpoints for mobile devices\n- Improve accessibility with proper ARIA labels\n- Add dark mode support\n\nCloses #345, #367, #389" - }, - { - "hash": "q4r5s6t", - "author": "Lisa Rodriguez ", - "date": "2024-01-15T10:45:12Z", - "message": "fix(db): optimize slow query in user search functionality\n\nOptimized the user search query that was causing performance issues\non databases with large user counts. Query time reduced from 2.5s to 150ms.\n\n- Added composite index on (email, username, created_at)\n- Refactored query to use more efficient JOIN structure\n- Added query result caching for common search patterns\n\nFixes #456" - }, - { - "hash": "u7v8w9x", - "author": "Tom Anderson ", - "date": "2024-01-15T09:30:55Z", - "message": "chore(deps): upgrade React to version 18.2.0\n\nUpgrade React and related dependencies to latest stable versions.\nThis includes performance improvements and new concurrent features.\n\n- React: 17.0.2 → 18.2.0\n- React-DOM: 17.0.2 → 18.2.0\n- React-Router: 6.8.0 → 6.8.1\n- Updated all peer dependencies" - }, - { - "hash": "y1z2a3b", - "author": "Jennifer Kim ", - "date": "2024-01-15T08:15:33Z", - "message": "test(auth): add comprehensive tests for OAuth flow\n\nAdded unit and integration tests for the OAuth2 authentication system\nto ensure reliability and prevent regressions.\n\n- Unit tests for OAuth client configuration\n- Integration tests for complete auth flow\n- Mock providers for testing without external dependencies\n- Error scenario testing\n\nTest coverage increased from 72% to 89% for auth module." - }, - { - "hash": "c4d5e6f", - "author": "Alex Thompson ", - "date": "2024-01-15T07:45:20Z", - "message": "perf(image): implement WebP compression reducing size by 40%\n\nReplaced PNG compression with WebP format for uploaded images.\nThis reduces average image file sizes by 40% while maintaining\nvisual quality, improving page load times and reducing bandwidth costs.\n\n- Add WebP encoding support\n- Implement fallback to PNG for older browsers\n- Add quality settings configuration\n- Update image serving endpoints\n\nPerformance improvement: Page load time reduced by 25% on average." - }, - { - "hash": "g7h8i9j", - "author": "Rachel Green ", - "date": "2024-01-14T16:20:10Z", - "message": "feat(payment): add Stripe payment processor integration\n\nIntegrate Stripe as a payment processor to support credit card payments.\nThis enables users to purchase premium features and subscriptions.\n\n- Add Stripe SDK integration\n- Implement payment intent flow\n- Add webhook handling for payment status updates\n- Include comprehensive error handling and logging\n- Add payment method management for users\n\nCloses #567\nCo-authored-by: Payment Team " - }, - { - "hash": "k1l2m3n", - "author": "Chris Martinez ", - "date": "2024-01-14T15:30:45Z", - "message": "fix(ui): resolve mobile navigation menu overflow issue\n\nFixed navigation menu overflow on mobile devices where long menu items\nwere being cut off and causing horizontal scrolling issues.\n\n- Implement responsive text wrapping\n- Add horizontal scrolling for overflowing content\n- Improve touch targets for better mobile usability\n- Fix z-index conflicts with dropdown menus\n\nFixes #678\nTested on iOS Safari, Chrome Mobile, and Firefox Mobile" - }, - { - "hash": "o4p5q6r", - "author": "Anna Kowalski ", - "date": "2024-01-14T14:20:15Z", - "message": "refactor(api): extract validation logic into reusable middleware\n\nExtracted common validation logic from individual API endpoints into\nreusable middleware functions to reduce code duplication and improve\nmaintainability.\n\n- Create validation middleware for common patterns\n- Refactor user, product, and order endpoints\n- Add comprehensive error messages\n- Improve validation performance by 30%" - }, - { - "hash": "s7t8u9v", - "author": "Kevin Park ", - "date": "2024-01-14T13:10:30Z", - "message": "feat(search): implement fuzzy search with Elasticsearch\n\nImplemented fuzzy search functionality using Elasticsearch to provide\nbetter search results for users with typos or partial matches.\n\n- Integrate Elasticsearch cluster\n- Add fuzzy matching with configurable distance\n- Implement search result ranking algorithm\n- Add search analytics and logging\n\nSearch accuracy improved by 35% in user testing.\nCloses #789" - }, - { - "hash": "w1x2y3z", - "author": "Security Team ", - "date": "2024-01-14T12:45:22Z", - "message": "fix(security): patch SQL injection vulnerability in reports\n\nPatched SQL injection vulnerability in the reports generation endpoint\nthat could allow unauthorized access to sensitive data.\n\n- Implement parameterized queries for all report filters\n- Add input sanitization and validation\n- Update security audit logging\n- Add automated security tests\n\nSeverity: HIGH - CVE-2024-0001\nReported by: External security researcher" - } -] \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_git_log_full.txt b/engineering/skills/release-manager/assets/sample_git_log_full.txt deleted file mode 100644 index 448b28a6..00000000 --- a/engineering/skills/release-manager/assets/sample_git_log_full.txt +++ /dev/null @@ -1,163 +0,0 @@ -commit a1b2c3d4e5f6789012345678901234567890abcd -Author: Sarah Johnson -Date: Mon Jan 15 14:30:22 2024 +0000 - - feat(auth): add OAuth2 integration with Google and GitHub - - Implement OAuth2 authentication flow supporting Google and GitHub providers. - Users can now sign in using their existing social media accounts, improving - user experience and reducing password fatigue. - - - Add OAuth2 client configuration - - Implement authorization code flow - - Add user profile mapping from providers - - Include comprehensive error handling - - Closes #123 - Resolves #145 - -commit e4f5g6h7i8j9012345678901234567890123abcdef -Author: Mike Chen -Date: Mon Jan 15 13:45:18 2024 +0000 - - fix(api): resolve race condition in user creation endpoint - - Fixed a race condition that occurred when multiple requests attempted - to create users with the same email address simultaneously. This was - causing duplicate user records in some edge cases. - - - Added database unique constraint on email field - - Implemented proper error handling for constraint violations - - Added retry logic with exponential backoff - - Fixes #234 - -commit i7j8k9l0m1n2345678901234567890123456789abcd -Author: Emily Davis -Date: Mon Jan 15 12:20:45 2024 +0000 - - docs(readme): update installation and deployment instructions - - Updated README with comprehensive installation guide including: - - Docker setup instructions - - Environment variable configuration - - Database migration steps - - Troubleshooting common issues - -commit m1n2o3p4q5r6789012345678901234567890abcdefg -Author: David Wilson -Date: Mon Jan 15 11:15:30 2024 +0000 - - feat(ui)!: redesign dashboard with new component library - - Complete redesign of the user dashboard using our new component library. - This provides better accessibility, improved mobile responsiveness, and - a more modern user interface. - - BREAKING CHANGE: The dashboard API endpoints have changed structure. - Frontend clients must update to use the new /v2/dashboard endpoints. - The legacy /v1/dashboard endpoints will be removed in version 3.0.0. - - - Implement new Card, Grid, and Chart components - - Add responsive breakpoints for mobile devices - - Improve accessibility with proper ARIA labels - - Add dark mode support - - Closes #345, #367, #389 - -commit q4r5s6t7u8v9012345678901234567890123456abcd -Author: Lisa Rodriguez -Date: Mon Jan 15 10:45:12 2024 +0000 - - fix(db): optimize slow query in user search functionality - - Optimized the user search query that was causing performance issues - on databases with large user counts. Query time reduced from 2.5s to 150ms. - - - Added composite index on (email, username, created_at) - - Refactored query to use more efficient JOIN structure - - Added query result caching for common search patterns - - Fixes #456 - -commit u7v8w9x0y1z2345678901234567890123456789abcde -Author: Tom Anderson -Date: Mon Jan 15 09:30:55 2024 +0000 - - chore(deps): upgrade React to version 18.2.0 - - Upgrade React and related dependencies to latest stable versions. - This includes performance improvements and new concurrent features. - - - React: 17.0.2 → 18.2.0 - - React-DOM: 17.0.2 → 18.2.0 - - React-Router: 6.8.0 → 6.8.1 - - Updated all peer dependencies - -commit y1z2a3b4c5d6789012345678901234567890abcdefg -Author: Jennifer Kim -Date: Mon Jan 15 08:15:33 2024 +0000 - - test(auth): add comprehensive tests for OAuth flow - - Added unit and integration tests for the OAuth2 authentication system - to ensure reliability and prevent regressions. - - - Unit tests for OAuth client configuration - - Integration tests for complete auth flow - - Mock providers for testing without external dependencies - - Error scenario testing - - Test coverage increased from 72% to 89% for auth module. - -commit c4d5e6f7g8h9012345678901234567890123456abcd -Author: Alex Thompson -Date: Mon Jan 15 07:45:20 2024 +0000 - - perf(image): implement WebP compression reducing size by 40% - - Replaced PNG compression with WebP format for uploaded images. - This reduces average image file sizes by 40% while maintaining - visual quality, improving page load times and reducing bandwidth costs. - - - Add WebP encoding support - - Implement fallback to PNG for older browsers - - Add quality settings configuration - - Update image serving endpoints - - Performance improvement: Page load time reduced by 25% on average. - -commit g7h8i9j0k1l2345678901234567890123456789abcde -Author: Rachel Green -Date: Sun Jan 14 16:20:10 2024 +0000 - - feat(payment): add Stripe payment processor integration - - Integrate Stripe as a payment processor to support credit card payments. - This enables users to purchase premium features and subscriptions. - - - Add Stripe SDK integration - - Implement payment intent flow - - Add webhook handling for payment status updates - - Include comprehensive error handling and logging - - Add payment method management for users - - Closes #567 - Co-authored-by: Payment Team - -commit k1l2m3n4o5p6789012345678901234567890abcdefg -Author: Chris Martinez -Date: Sun Jan 14 15:30:45 2024 +0000 - - fix(ui): resolve mobile navigation menu overflow issue - - Fixed navigation menu overflow on mobile devices where long menu items - were being cut off and causing horizontal scrolling issues. - - - Implement responsive text wrapping - - Add horizontal scrolling for overflowing content - - Improve touch targets for better mobile usability - - Fix z-index conflicts with dropdown menus - - Fixes #678 - Tested on iOS Safari, Chrome Mobile, and Firefox Mobile \ No newline at end of file diff --git a/engineering/skills/release-manager/assets/sample_release_plan.json b/engineering/skills/release-manager/assets/sample_release_plan.json deleted file mode 100644 index 8b9e6652..00000000 --- a/engineering/skills/release-manager/assets/sample_release_plan.json +++ /dev/null @@ -1,273 +0,0 @@ -{ - "release_name": "Winter 2024 Release", - "version": "2.3.0", - "target_date": "2024-02-15T10:00:00Z", - "features": [ - { - "id": "AUTH-123", - "title": "OAuth2 Integration", - "description": "Add support for Google and GitHub OAuth2 authentication", - "type": "feature", - "assignee": "sarah.johnson@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/234", - "issue_url": "https://github.com/ourapp/backend/issues/123", - "risk_level": "medium", - "test_coverage_required": 85.0, - "test_coverage_actual": 89.5, - "requires_migration": false, - "breaking_changes": [], - "dependencies": ["AUTH-124"], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "UI-345", - "title": "Dashboard Redesign", - "description": "Complete redesign of user dashboard with new component library", - "type": "breaking_change", - "assignee": "david.wilson@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/frontend/pull/456", - "issue_url": "https://github.com/ourapp/frontend/issues/345", - "risk_level": "high", - "test_coverage_required": 90.0, - "test_coverage_actual": 92.3, - "requires_migration": true, - "migration_complexity": "moderate", - "breaking_changes": [ - "Dashboard API endpoints changed from /v1/dashboard to /v2/dashboard", - "Dashboard widget configuration format updated" - ], - "dependencies": [], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "PAY-567", - "title": "Stripe Payment Integration", - "description": "Add Stripe as payment processor for premium features", - "type": "feature", - "assignee": "rachel.green@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/678", - "issue_url": "https://github.com/ourapp/backend/issues/567", - "risk_level": "high", - "test_coverage_required": 95.0, - "test_coverage_actual": 97.2, - "requires_migration": true, - "migration_complexity": "complex", - "breaking_changes": [], - "dependencies": ["SEC-890"], - "qa_approved": true, - "security_approved": true, - "pm_approved": true - }, - { - "id": "SEARCH-789", - "title": "Elasticsearch Fuzzy Search", - "description": "Implement fuzzy search functionality with Elasticsearch", - "type": "feature", - "assignee": "kevin.park@example.com", - "status": "in_progress", - "pull_request_url": "https://github.com/ourapp/backend/pull/890", - "issue_url": "https://github.com/ourapp/backend/issues/789", - "risk_level": "medium", - "test_coverage_required": 80.0, - "test_coverage_actual": 76.5, - "requires_migration": true, - "migration_complexity": "moderate", - "breaking_changes": [], - "dependencies": ["INFRA-234"], - "qa_approved": false, - "security_approved": true, - "pm_approved": true - }, - { - "id": "MOBILE-456", - "title": "Biometric Authentication", - "description": "Add fingerprint and face ID support for mobile apps", - "type": "feature", - "assignee": "alex.thompson@example.com", - "status": "blocked", - "pull_request_url": null, - "issue_url": "https://github.com/ourapp/mobile/issues/456", - "risk_level": "medium", - "test_coverage_required": 85.0, - "test_coverage_actual": null, - "requires_migration": false, - "breaking_changes": [], - "dependencies": ["AUTH-123"], - "qa_approved": false, - "security_approved": false, - "pm_approved": true - }, - { - "id": "PERF-678", - "title": "Redis Caching Implementation", - "description": "Implement Redis caching for frequently accessed data", - "type": "performance", - "assignee": "lisa.rodriguez@example.com", - "status": "ready", - "pull_request_url": "https://github.com/ourapp/backend/pull/901", - "issue_url": "https://github.com/ourapp/backend/issues/678", - "risk_level": "low", - "test_coverage_required": 75.0, - "test_coverage_actual": 82.1, - "requires_migration": false, - "breaking_changes": [], - "dependencies": [], - "qa_approved": true, - "security_approved": false, - "pm_approved": true - } - ], - "quality_gates": [ - { - "name": "Unit Test Coverage", - "required": true, - "status": "ready", - "details": "Overall test coverage above 85% threshold", - "threshold": 85.0, - "actual_value": 87.3 - }, - { - "name": "Integration Tests", - "required": true, - "status": "ready", - "details": "All integration tests passing" - }, - { - "name": "Security Scan", - "required": true, - "status": "pending", - "details": "Waiting for security team review of payment integration" - }, - { - "name": "Performance Testing", - "required": true, - "status": "ready", - "details": "Load testing shows 99th percentile response time under 500ms" - }, - { - "name": "Documentation Review", - "required": true, - "status": "pending", - "details": "API documentation needs update for dashboard changes" - }, - { - "name": "Dependency Audit", - "required": true, - "status": "ready", - "details": "No high or critical vulnerabilities found" - } - ], - "stakeholders": [ - { - "name": "Engineering Team", - "role": "developer", - "contact": "engineering@example.com", - "notification_type": "slack", - "critical_path": true - }, - { - "name": "Product Team", - "role": "pm", - "contact": "product@example.com", - "notification_type": "email", - "critical_path": true - }, - { - "name": "QA Team", - "role": "qa", - "contact": "qa@example.com", - "notification_type": "slack", - "critical_path": true - }, - { - "name": "Security Team", - "role": "security", - "contact": "security@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Customer Support", - "role": "support", - "contact": "support@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Sales Team", - "role": "sales", - "contact": "sales@example.com", - "notification_type": "email", - "critical_path": false - }, - { - "name": "Beta Users", - "role": "customer", - "contact": "beta-users@example.com", - "notification_type": "email", - "critical_path": false - } - ], - "rollback_steps": [ - { - "order": 1, - "description": "Alert incident response team and stakeholders", - "estimated_time": "2 minutes", - "risk_level": "low", - "verification": "Confirm team is aware and responding via Slack" - }, - { - "order": 2, - "description": "Switch load balancer to previous version", - "command": "kubectl patch service app --patch '{\"spec\": {\"selector\": {\"version\": \"v2.2.1\"}}}'", - "estimated_time": "30 seconds", - "risk_level": "low", - "verification": "Check traffic routing to previous version via monitoring dashboard" - }, - { - "order": 3, - "description": "Disable new feature flags", - "command": "curl -X POST https://api.example.com/feature-flags/oauth2/disable", - "estimated_time": "1 minute", - "risk_level": "low", - "verification": "Verify feature flags are disabled in admin panel" - }, - { - "order": 4, - "description": "Roll back database migrations", - "command": "python manage.py migrate app 0042", - "estimated_time": "10 minutes", - "risk_level": "high", - "verification": "Verify database schema and run data integrity checks" - }, - { - "order": 5, - "description": "Clear Redis cache", - "command": "redis-cli FLUSHALL", - "estimated_time": "30 seconds", - "risk_level": "medium", - "verification": "Confirm cache is cleared and application rebuilds cache properly" - }, - { - "order": 6, - "description": "Verify application health", - "estimated_time": "5 minutes", - "risk_level": "low", - "verification": "Check health endpoints, error rates, and core user workflows" - }, - { - "order": 7, - "description": "Update status page and notify users", - "estimated_time": "5 minutes", - "risk_level": "low", - "verification": "Confirm status page updated and notifications sent" - } - ] -} \ No newline at end of file diff --git a/engineering/skills/release-manager/changelog_generator.py b/engineering/skills/release-manager/changelog_generator.py deleted file mode 100644 index f50e65b4..00000000 --- a/engineering/skills/release-manager/changelog_generator.py +++ /dev/null @@ -1,504 +0,0 @@ -#!/usr/bin/env python3 -""" -Changelog Generator - -Parses git log output in conventional commits format and generates structured changelogs -in multiple formats (Markdown, Keep a Changelog). Groups commits by type, extracts scope, -links to PRs/issues, and highlights breaking changes. - -Input: git log text (piped from git log) or JSON array of commits -Output: formatted CHANGELOG.md section + release summary stats -""" - -import argparse -import json -import re -import sys -from collections import defaultdict, Counter -from datetime import datetime -from typing import Dict, List, Optional, Tuple, Union - - -class ConventionalCommit: - """Represents a parsed conventional commit.""" - - def __init__(self, raw_message: str, commit_hash: str = "", author: str = "", - date: str = "", merge_info: Optional[str] = None): - self.raw_message = raw_message - self.commit_hash = commit_hash - self.author = author - self.date = date - self.merge_info = merge_info - - # Parse the commit message - self.type = "" - self.scope = "" - self.description = "" - self.body = "" - self.footers = [] - self.is_breaking = False - self.breaking_change_description = "" - - self._parse_commit_message() - - def _parse_commit_message(self): - """Parse conventional commit format.""" - lines = self.raw_message.split('\n') - header = lines[0] if lines else "" - - # Parse header: type(scope): description - header_pattern = r'^(\w+)(\([^)]+\))?(!)?:\s*(.+)$' - match = re.match(header_pattern, header) - - if match: - self.type = match.group(1).lower() - scope_match = match.group(2) - self.scope = scope_match[1:-1] if scope_match else "" # Remove parentheses - self.is_breaking = bool(match.group(3)) # ! indicates breaking change - self.description = match.group(4).strip() - else: - # Fallback for non-conventional commits - self.type = "chore" - self.description = header - - # Parse body and footers - if len(lines) > 1: - body_lines = [] - footer_lines = [] - in_footer = False - - for line in lines[1:]: - if not line.strip(): - continue - - # Check if this is a footer (KEY: value or KEY #value format) - footer_pattern = r'^([A-Z-]+):\s*(.+)$|^([A-Z-]+)\s+#(\d+)$' - if re.match(footer_pattern, line): - in_footer = True - footer_lines.append(line) - - # Check for breaking change - if line.startswith('BREAKING CHANGE:'): - self.is_breaking = True - self.breaking_change_description = line[16:].strip() - else: - if in_footer: - # Continuation of footer - footer_lines.append(line) - else: - body_lines.append(line) - - self.body = '\n'.join(body_lines).strip() - self.footers = footer_lines - - def extract_issue_references(self) -> List[str]: - """Extract issue/PR references like #123, fixes #456, etc.""" - text = f"{self.description} {self.body} {' '.join(self.footers)}" - - # Common patterns for issue references - patterns = [ - r'#(\d+)', # Simple #123 - r'(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)', # closes #123 - r'(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+(\w+/\w+)?#(\d+)' # fixes repo#123 - ] - - references = [] - for pattern in patterns: - matches = re.findall(pattern, text, re.IGNORECASE) - for match in matches: - if isinstance(match, tuple): - # Handle tuple results from more complex patterns - ref = match[-1] if match[-1] else match[0] - else: - ref = match - if ref and ref not in references: - references.append(ref) - - return references - - def get_changelog_category(self) -> str: - """Map commit type to changelog category.""" - category_map = { - 'feat': 'Added', - 'add': 'Added', - 'fix': 'Fixed', - 'bugfix': 'Fixed', - 'security': 'Security', - 'perf': 'Fixed', # Performance improvements go to Fixed - 'refactor': 'Changed', - 'style': 'Changed', - 'docs': 'Changed', - 'test': None, # Tests don't appear in user-facing changelog - 'ci': None, - 'build': None, - 'chore': None, - 'revert': 'Fixed', - 'remove': 'Removed', - 'deprecate': 'Deprecated' - } - - return category_map.get(self.type, 'Changed') - - -class ChangelogGenerator: - """Main changelog generator class.""" - - def __init__(self): - self.commits: List[ConventionalCommit] = [] - self.version = "Unreleased" - self.date = datetime.now().strftime("%Y-%m-%d") - self.base_url = "" - - def parse_git_log_output(self, git_log_text: str): - """Parse git log output into ConventionalCommit objects.""" - # Try to detect format based on patterns in the text - lines = git_log_text.strip().split('\n') - - if not lines or not lines[0]: - return - - # Format 1: Simple oneline format (hash message) - oneline_pattern = r'^([a-f0-9]{7,40})\s+(.+)$' - - # Format 2: Full format with metadata - full_pattern = r'^commit\s+([a-f0-9]+)' - - current_commit = None - commit_buffer = [] - - for line in lines: - line = line.strip() - if not line: - continue - - # Check if this is a new commit (oneline format) - oneline_match = re.match(oneline_pattern, line) - if oneline_match: - # Process previous commit - if current_commit: - self.commits.append(current_commit) - - # Start new commit - commit_hash = oneline_match.group(1) - message = oneline_match.group(2) - current_commit = ConventionalCommit(message, commit_hash) - continue - - # Check if this is a new commit (full format) - full_match = re.match(full_pattern, line) - if full_match: - # Process previous commit - if current_commit: - commit_message = '\n'.join(commit_buffer).strip() - if commit_message: - current_commit = ConventionalCommit(commit_message, current_commit.commit_hash, - current_commit.author, current_commit.date) - self.commits.append(current_commit) - - # Start new commit - commit_hash = full_match.group(1) - current_commit = ConventionalCommit("", commit_hash) - commit_buffer = [] - continue - - # Parse metadata lines in full format - if current_commit and not current_commit.raw_message: - if line.startswith('Author:'): - current_commit.author = line[7:].strip() - elif line.startswith('Date:'): - current_commit.date = line[5:].strip() - elif line.startswith('Merge:'): - current_commit.merge_info = line[6:].strip() - elif line.startswith(' '): - # Commit message line (indented) - commit_buffer.append(line[4:]) # Remove 4-space indent - - # Process final commit - if current_commit: - if commit_buffer: - commit_message = '\n'.join(commit_buffer).strip() - current_commit = ConventionalCommit(commit_message, current_commit.commit_hash, - current_commit.author, current_commit.date) - self.commits.append(current_commit) - - def parse_json_commits(self, json_data: Union[str, List[Dict]]): - """Parse commits from JSON format.""" - if isinstance(json_data, str): - data = json.loads(json_data) - else: - data = json_data - - for commit_data in data: - commit = ConventionalCommit( - raw_message=commit_data.get('message', ''), - commit_hash=commit_data.get('hash', ''), - author=commit_data.get('author', ''), - date=commit_data.get('date', '') - ) - self.commits.append(commit) - - def group_commits_by_category(self) -> Dict[str, List[ConventionalCommit]]: - """Group commits by changelog category.""" - categories = defaultdict(list) - - for commit in self.commits: - category = commit.get_changelog_category() - if category: # Skip None categories (internal changes) - categories[category].append(commit) - - return dict(categories) - - def generate_markdown_changelog(self, include_unreleased: bool = True) -> str: - """Generate Keep a Changelog format markdown.""" - grouped_commits = self.group_commits_by_category() - - if not grouped_commits: - return "No notable changes.\n" - - # Start with header - changelog = [] - if include_unreleased and self.version == "Unreleased": - changelog.append(f"## [{self.version}]") - else: - changelog.append(f"## [{self.version}] - {self.date}") - - changelog.append("") - - # Order categories logically - category_order = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security'] - - # Separate breaking changes - breaking_changes = [commit for commit in self.commits if commit.is_breaking] - - # Add breaking changes section first if any exist - if breaking_changes: - changelog.append("### Breaking Changes") - for commit in breaking_changes: - line = self._format_commit_line(commit, show_breaking=True) - changelog.append(f"- {line}") - changelog.append("") - - # Add regular categories - for category in category_order: - if category not in grouped_commits: - continue - - changelog.append(f"### {category}") - - # Group by scope for better organization - scoped_commits = defaultdict(list) - for commit in grouped_commits[category]: - scope = commit.scope if commit.scope else "general" - scoped_commits[scope].append(commit) - - # Sort scopes, with 'general' last - scopes = sorted(scoped_commits.keys()) - if "general" in scopes: - scopes.remove("general") - scopes.append("general") - - for scope in scopes: - if len(scoped_commits) > 1 and scope != "general": - changelog.append(f"#### {scope.title()}") - - for commit in scoped_commits[scope]: - line = self._format_commit_line(commit) - changelog.append(f"- {line}") - - changelog.append("") - - return '\n'.join(changelog) - - def _format_commit_line(self, commit: ConventionalCommit, show_breaking: bool = False) -> str: - """Format a single commit line for the changelog.""" - # Start with description - line = commit.description.capitalize() - - # Add scope if present and not already in description - if commit.scope and commit.scope.lower() not in line.lower(): - line = f"{commit.scope}: {line}" - - # Add issue references - issue_refs = commit.extract_issue_references() - if issue_refs: - refs_str = ', '.join(f"#{ref}" for ref in issue_refs) - line += f" ({refs_str})" - - # Add commit hash if available - if commit.commit_hash: - short_hash = commit.commit_hash[:7] - line += f" [{short_hash}]" - - if self.base_url: - line += f"({self.base_url}/commit/{commit.commit_hash})" - - # Add breaking change indicator - if show_breaking and commit.breaking_change_description: - line += f" - {commit.breaking_change_description}" - elif commit.is_breaking and not show_breaking: - line += " ⚠️ BREAKING" - - return line - - def generate_release_summary(self) -> Dict: - """Generate summary statistics for the release.""" - if not self.commits: - return { - 'version': self.version, - 'date': self.date, - 'total_commits': 0, - 'by_type': {}, - 'by_author': {}, - 'breaking_changes': 0, - 'notable_changes': 0 - } - - # Count by type - type_counts = Counter(commit.type for commit in self.commits) - - # Count by author - author_counts = Counter(commit.author for commit in self.commits if commit.author) - - # Count breaking changes - breaking_count = sum(1 for commit in self.commits if commit.is_breaking) - - # Count notable changes (excluding chore, ci, build, test) - notable_types = {'feat', 'fix', 'security', 'perf', 'refactor', 'remove', 'deprecate'} - notable_count = sum(1 for commit in self.commits if commit.type in notable_types) - - return { - 'version': self.version, - 'date': self.date, - 'total_commits': len(self.commits), - 'by_type': dict(type_counts.most_common()), - 'by_author': dict(author_counts.most_common(10)), # Top 10 contributors - 'breaking_changes': breaking_count, - 'notable_changes': notable_count, - 'scopes': list(set(commit.scope for commit in self.commits if commit.scope)), - 'issue_references': len(set().union(*(commit.extract_issue_references() for commit in self.commits))) - } - - def generate_json_output(self) -> str: - """Generate JSON representation of the changelog data.""" - grouped_commits = self.group_commits_by_category() - - # Convert commits to serializable format - json_data = { - 'version': self.version, - 'date': self.date, - 'summary': self.generate_release_summary(), - 'categories': {} - } - - for category, commits in grouped_commits.items(): - json_data['categories'][category] = [] - for commit in commits: - commit_data = { - 'type': commit.type, - 'scope': commit.scope, - 'description': commit.description, - 'hash': commit.commit_hash, - 'author': commit.author, - 'date': commit.date, - 'breaking': commit.is_breaking, - 'breaking_description': commit.breaking_change_description, - 'issue_references': commit.extract_issue_references() - } - json_data['categories'][category].append(commit_data) - - return json.dumps(json_data, indent=2) - - -def main(): - """Main entry point with CLI argument parsing.""" - parser = argparse.ArgumentParser(description="Generate changelog from conventional commits") - parser.add_argument('--input', '-i', type=str, help='Input file (default: stdin)') - parser.add_argument('--format', '-f', choices=['markdown', 'json', 'both'], - default='markdown', help='Output format') - parser.add_argument('--version', '-v', type=str, default='Unreleased', - help='Version for this release') - parser.add_argument('--date', '-d', type=str, - default=datetime.now().strftime("%Y-%m-%d"), - help='Release date (YYYY-MM-DD format)') - parser.add_argument('--base-url', '-u', type=str, default='', - help='Base URL for commit links') - parser.add_argument('--input-format', choices=['git-log', 'json'], - default='git-log', help='Input format') - parser.add_argument('--output', '-o', type=str, help='Output file (default: stdout)') - parser.add_argument('--summary', '-s', action='store_true', - help='Include release summary statistics') - - args = parser.parse_args() - - # Read input - if args.input: - with open(args.input, 'r', encoding='utf-8') as f: - input_data = f.read() - else: - input_data = sys.stdin.read() - - if not input_data.strip(): - print("No input data provided", file=sys.stderr) - sys.exit(1) - - # Initialize generator - generator = ChangelogGenerator() - generator.version = args.version - generator.date = args.date - generator.base_url = args.base_url - - # Parse input - try: - if args.input_format == 'json': - generator.parse_json_commits(input_data) - else: - generator.parse_git_log_output(input_data) - except Exception as e: - print(f"Error parsing input: {e}", file=sys.stderr) - sys.exit(1) - - if not generator.commits: - print("No valid commits found in input", file=sys.stderr) - sys.exit(1) - - # Generate output - output_lines = [] - - if args.format in ['markdown', 'both']: - changelog_md = generator.generate_markdown_changelog() - if args.format == 'both': - output_lines.append("# Markdown Changelog\n") - output_lines.append(changelog_md) - - if args.format in ['json', 'both']: - changelog_json = generator.generate_json_output() - if args.format == 'both': - output_lines.append("\n# JSON Output\n") - output_lines.append(changelog_json) - - if args.summary: - summary = generator.generate_release_summary() - output_lines.append(f"\n# Release Summary") - output_lines.append(f"- **Version:** {summary['version']}") - output_lines.append(f"- **Total Commits:** {summary['total_commits']}") - output_lines.append(f"- **Notable Changes:** {summary['notable_changes']}") - output_lines.append(f"- **Breaking Changes:** {summary['breaking_changes']}") - output_lines.append(f"- **Issue References:** {summary['issue_references']}") - - if summary['by_type']: - output_lines.append("- **By Type:**") - for commit_type, count in summary['by_type'].items(): - output_lines.append(f" - {commit_type}: {count}") - - # Write output - final_output = '\n'.join(output_lines) - - if args.output: - with open(args.output, 'w', encoding='utf-8') as f: - f.write(final_output) - else: - print(final_output) - - -if __name__ == '__main__': - main() \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/changelog_example.md b/engineering/skills/release-manager/expected_outputs/changelog_example.md deleted file mode 100644 index 2d6112a9..00000000 --- a/engineering/skills/release-manager/expected_outputs/changelog_example.md +++ /dev/null @@ -1,37 +0,0 @@ -# Expected Changelog Output - -## [2.3.0] - 2024-01-15 - -### Breaking Changes -- ui: redesign dashboard with new component library - The dashboard API endpoints have changed structure. Frontend clients must update to use the new /v2/dashboard endpoints. The legacy /v1/dashboard endpoints will be removed in version 3.0.0. (#345, #367, #389) [m1n2o3p] - -### Added -- auth: add OAuth2 integration with Google and GitHub (#123, #145) [a1b2c3d] -- payment: add Stripe payment processor integration (#567) [g7h8i9j] -- search: implement fuzzy search with Elasticsearch (#789) [s7t8u9v] - -### Fixed -- api: resolve race condition in user creation endpoint (#234) [e4f5g6h] -- db: optimize slow query in user search functionality (#456) [q4r5s6t] -- ui: resolve mobile navigation menu overflow issue (#678) [k1l2m3n] -- security: patch SQL injection vulnerability in reports [w1x2y3z] ⚠️ BREAKING - -### Changed -- image: implement WebP compression reducing size by 40% [c4d5e6f] -- api: extract validation logic into reusable middleware [o4p5q6r] -- readme: update installation and deployment instructions [i7j8k9l] - -# Release Summary -- **Version:** 2.3.0 -- **Total Commits:** 13 -- **Notable Changes:** 9 -- **Breaking Changes:** 2 -- **Issue References:** 8 -- **By Type:** - - feat: 4 - - fix: 4 - - perf: 1 - - refactor: 1 - - docs: 1 - - test: 1 - - chore: 1 \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt b/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt deleted file mode 100644 index 1e986876..00000000 --- a/engineering/skills/release-manager/expected_outputs/release_readiness_example.txt +++ /dev/null @@ -1,30 +0,0 @@ -Release Readiness Report -======================== -Release: Winter 2024 Release v2.3.0 -Status: AT_RISK -Readiness Score: 73.3% - -WARNINGS: - - ⚠️ Feature 'Elasticsearch Fuzzy Search' (SEARCH-789) still in progress - ⚠️ Feature 'Elasticsearch Fuzzy Search' has low test coverage: 76.5% < 80.0% - ⚠️ Required quality gate 'Security Scan' is pending - ⚠️ Required quality gate 'Documentation Review' is pending - -BLOCKING ISSUES: - - ❌ Feature 'Biometric Authentication' (MOBILE-456) is blocked - ❌ Feature 'Biometric Authentication' missing approvals: QA approval, Security approval - -RECOMMENDATIONS: - - 💡 Obtain required approvals for pending features - 💡 Improve test coverage for features below threshold - 💡 Complete pending quality gate validations - -FEATURE SUMMARY: - Total: 6 | Ready: 3 | Blocked: 1 - Breaking Changes: 1 | Missing Approvals: 1 - -QUALITY GATES: - Total: 6 | Passed: 3 | Failed: 0 \ No newline at end of file diff --git a/engineering/skills/release-manager/expected_outputs/version_bump_example.txt b/engineering/skills/release-manager/expected_outputs/version_bump_example.txt deleted file mode 100644 index c7c9d3f5..00000000 --- a/engineering/skills/release-manager/expected_outputs/version_bump_example.txt +++ /dev/null @@ -1,31 +0,0 @@ -Current Version: 2.2.5 -Recommended Version: 3.0.0 -With v prefix: v3.0.0 -Bump Type: major - -Commit Analysis: -- Total commits: 13 -- Breaking changes: 2 -- New features: 4 -- Bug fixes: 4 -- Ignored commits: 3 - -Breaking Changes: - - feat(ui): redesign dashboard with new component library - - fix(security): patch SQL injection vulnerability in reports - -Bump Commands: - npm: - npm version 3.0.0 --no-git-tag-version - python: - # Update version in setup.py, __init__.py, or pyproject.toml - # pyproject.toml: version = "3.0.0" - rust: - # Update Cargo.toml - # version = "3.0.0" - git: - git tag -a v3.0.0 -m 'Release v3.0.0' - git push origin v3.0.0 - docker: - docker build -t myapp:3.0.0 . - docker tag myapp:3.0.0 myapp:latest \ No newline at end of file diff --git a/engineering/skills/release-manager/references/conventional-commits-guide.md b/engineering/skills/release-manager/references/conventional-commits-guide.md deleted file mode 100644 index 9162648a..00000000 --- a/engineering/skills/release-manager/references/conventional-commits-guide.md +++ /dev/null @@ -1,341 +0,0 @@ -# Conventional Commits Guide - -## Overview - -Conventional Commits is a specification for adding human and machine readable meaning to commit messages. The specification provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools for version management, changelog generation, and release planning. - -## Basic Format - -``` -[optional scope]: - -[optional body] - -[optional footer(s)] -``` - -## Commit Types - -### Primary Types - -- **feat**: A new feature for the user (correlates with MINOR in semantic versioning) -- **fix**: A bug fix for the user (correlates with PATCH in semantic versioning) - -### Secondary Types - -- **build**: Changes that affect the build system or external dependencies (webpack, npm, etc.) -- **ci**: Changes to CI configuration files and scripts (Travis, Circle, BrowserStack, SauceLabs) -- **docs**: Documentation only changes -- **perf**: A code change that improves performance -- **refactor**: A code change that neither fixes a bug nor adds a feature -- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) -- **test**: Adding missing tests or correcting existing tests -- **chore**: Other changes that don't modify src or test files -- **revert**: Reverts a previous commit - -### Breaking Changes - -Any commit can introduce a breaking change by: -1. Adding `!` after the type: `feat!: remove deprecated API` -2. Including `BREAKING CHANGE:` in the footer - -## Scopes - -Scopes provide additional contextual information about the change. They should be noun describing a section of the codebase: - -- `auth` - Authentication and authorization -- `api` - API changes -- `ui` - User interface -- `db` - Database related changes -- `config` - Configuration changes -- `deps` - Dependency updates - -## Examples - -### Simple Feature -``` -feat(auth): add OAuth2 integration - -Integrate OAuth2 authentication with Google and GitHub providers. -Users can now log in using their existing social media accounts. -``` - -### Bug Fix -``` -fix(api): resolve race condition in user creation - -When multiple requests tried to create users with the same email -simultaneously, duplicate records were sometimes created. Added -proper database constraints and error handling. - -Fixes #234 -``` - -### Breaking Change with ! -``` -feat(api)!: remove deprecated /v1/users endpoint - -The deprecated /v1/users endpoint has been removed. All clients -should migrate to /v2/users which provides better performance -and additional features. - -BREAKING CHANGE: /v1/users endpoint removed, use /v2/users instead -``` - -### Breaking Change with Footer -``` -feat(auth): implement new authentication flow - -Add support for multi-factor authentication and improved session -management. This change requires all users to re-authenticate. - -BREAKING CHANGE: Authentication tokens issued before this release -are no longer valid. Users must log in again. -``` - -### Performance Improvement -``` -perf(image): optimize image compression algorithm - -Replaced PNG compression with WebP format, reducing image sizes -by 40% on average while maintaining visual quality. - -Closes #456 -``` - -### Dependency Update -``` -build(deps): upgrade React to version 18.2.0 - -Updates React and related packages to latest stable versions. -Includes performance improvements and new concurrent features. -``` - -### Documentation -``` -docs(readme): add deployment instructions - -Added comprehensive deployment guide including Docker setup, -environment variables configuration, and troubleshooting tips. -``` - -### Revert -``` -revert: feat(payment): add cryptocurrency support - -This reverts commit 667ecc1654a317a13331b17617d973392f415f02. - -Reverting due to security concerns identified in code review. -The feature will be re-implemented with proper security measures. -``` - -## Multi-paragraph Body - -For complex changes, use multiple paragraphs in the body: - -``` -feat(search): implement advanced search functionality - -Add support for complex search queries including: -- Boolean operators (AND, OR, NOT) -- Field-specific searches (title:, author:, date:) -- Fuzzy matching with configurable threshold -- Search result highlighting - -The search index has been restructured to support these new -features while maintaining backward compatibility with existing -simple search queries. - -Performance testing shows less than 10ms impact on search -response times even with complex queries. - -Closes #789, #823, #901 -``` - -## Footers - -### Issue References -``` -Fixes #123 -Closes #234, #345 -Resolves #456 -``` - -### Breaking Changes -``` -BREAKING CHANGE: The `authenticate` function now requires a second -parameter for the authentication method. Update all calls from -`authenticate(token)` to `authenticate(token, 'bearer')`. -``` - -### Co-authors -``` -Co-authored-by: Jane Doe -Co-authored-by: John Smith -``` - -### Reviewed By -``` -Reviewed-by: Senior Developer -Acked-by: Tech Lead -``` - -## Automation Benefits - -Using conventional commits enables: - -### Automatic Version Bumping -- `fix` commits trigger PATCH version bump (1.0.0 → 1.0.1) -- `feat` commits trigger MINOR version bump (1.0.0 → 1.1.0) -- `BREAKING CHANGE` triggers MAJOR version bump (1.0.0 → 2.0.0) - -### Changelog Generation -```markdown -## [1.2.0] - 2024-01-15 - -### Added -- OAuth2 integration (auth) -- Advanced search functionality (search) - -### Fixed -- Race condition in user creation (api) -- Memory leak in image processing (image) - -### Breaking Changes -- Authentication tokens issued before this release are no longer valid -``` - -### Release Notes -Generate user-friendly release notes automatically from commit history, filtering out internal changes and highlighting user-facing improvements. - -## Best Practices - -### Writing Good Descriptions -- Use imperative mood: "add feature" not "added feature" -- Start with lowercase letter -- No period at the end -- Limit to 50 characters when possible -- Be specific and descriptive - -### Good Examples -``` -feat(auth): add password reset functionality -fix(ui): resolve mobile navigation menu overflow -perf(db): optimize user query with proper indexing -``` - -### Bad Examples -``` -feat: stuff -fix: bug -update: changes -``` - -### Body Guidelines -- Separate subject from body with blank line -- Wrap body at 72 characters -- Use body to explain what and why, not how -- Reference issues and PRs when relevant - -### Scope Guidelines -- Use consistent scope naming across the team -- Keep scopes short and meaningful -- Document your team's scope conventions -- Consider using scopes that match your codebase structure - -## Tools and Integration - -### Git Hooks -Use tools like `commitizen` or `husky` to enforce conventional commit format: - -```bash -# Install commitizen -npm install -g commitizen cz-conventional-changelog - -# Configure -echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc - -# Use -git cz -``` - -### Automated Validation -Add commit message validation to prevent non-conventional commits: - -```javascript -// commitlint.config.js -module.exports = { - extends: ['@commitlint/config-conventional'], - rules: { - 'type-enum': [ - 2, 'always', - ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'] - ], - 'subject-case': [2, 'always', 'lower-case'], - 'subject-max-length': [2, 'always', 50] - } -}; -``` - -### CI/CD Integration -Integrate with release automation tools: -- **semantic-release**: Automated version management and package publishing -- **standard-version**: Generate changelog and tag releases -- **release-please**: Google's release automation tool - -## Common Mistakes - -### Mixing Multiple Changes -``` -# Bad: Multiple unrelated changes -feat: add login page and fix CSS bug and update dependencies - -# Good: Separate commits -feat(auth): add login page -fix(ui): resolve CSS styling issue -build(deps): update React to version 18 -``` - -### Vague Descriptions -``` -# Bad: Not descriptive -fix: bug in code -feat: new stuff - -# Good: Specific and clear -fix(api): resolve null pointer exception in user validation -feat(search): implement fuzzy matching algorithm -``` - -### Missing Breaking Change Indicators -``` -# Bad: Breaking change not marked -feat(api): update user authentication - -# Good: Properly marked breaking change -feat(api)!: update user authentication - -BREAKING CHANGE: All API clients must now include authentication -headers in every request. Anonymous access is no longer supported. -``` - -## Team Guidelines - -### Establishing Conventions -1. **Define scope vocabulary**: Create a list of approved scopes for your project -2. **Document examples**: Provide team-specific examples of good commits -3. **Set up tooling**: Use linters and hooks to enforce standards -4. **Review process**: Include commit message quality in code reviews -5. **Training**: Ensure all team members understand the format - -### Scope Examples by Project Type -**Web Application:** -- `auth`, `ui`, `api`, `db`, `config`, `deploy` - -**Library/SDK:** -- `core`, `utils`, `docs`, `examples`, `tests` - -**Mobile App:** -- `ios`, `android`, `shared`, `ui`, `network`, `storage` - -By following conventional commits consistently, your team will have a clear, searchable commit history that enables powerful automation and improves the overall development workflow. \ No newline at end of file diff --git a/engineering/skills/release-manager/references/release-workflow-comparison.md b/engineering/skills/release-manager/references/release-workflow-comparison.md deleted file mode 100644 index 94f4fc4b..00000000 --- a/engineering/skills/release-manager/references/release-workflow-comparison.md +++ /dev/null @@ -1,410 +0,0 @@ -# Release Workflow Comparison - -## Overview - -This document compares the three most popular branching and release workflows: Git Flow, GitHub Flow, and Trunk-based Development. Each approach has distinct advantages and trade-offs depending on your team size, deployment frequency, and risk tolerance. - -## Git Flow - -### Structure -``` -main (production) - ↑ -release/1.2.0 ← develop (integration) ← feature/user-auth - ↑ ← feature/payment-api - hotfix/critical-fix -``` - -### Branch Types -- **main**: Production-ready code, tagged releases -- **develop**: Integration branch for next release -- **feature/***: Individual features, merged to develop -- **release/X.Y.Z**: Release preparation, branched from develop -- **hotfix/***: Critical fixes, branched from main - -### Typical Flow -1. Create feature branch from develop: `git checkout -b feature/login develop` -2. Work on feature, commit changes -3. Merge feature to develop when complete -4. When ready for release, create release branch: `git checkout -b release/1.2.0 develop` -5. Finalize release (version bump, changelog, bug fixes) -6. Merge release branch to both main and develop -7. Tag release: `git tag v1.2.0` -8. Deploy from main branch - -### Advantages -- **Clear separation** between production and development code -- **Stable main branch** always represents production state -- **Parallel development** of features without interference -- **Structured release process** with dedicated release branches -- **Hotfix support** without disrupting development work -- **Good for scheduled releases** and traditional release cycles - -### Disadvantages -- **Complex workflow** with many branch types -- **Merge overhead** from multiple integration points -- **Delayed feedback** from long-lived feature branches -- **Integration conflicts** when merging large features -- **Slower deployment** due to process overhead -- **Not ideal for continuous deployment** - -### Best For -- Large teams (10+ developers) -- Products with scheduled release cycles -- Enterprise software with formal testing phases -- Projects requiring stable release branches -- Teams comfortable with complex Git workflows - -### Example Commands -```bash -# Start new feature -git checkout develop -git checkout -b feature/user-authentication - -# Finish feature -git checkout develop -git merge --no-ff feature/user-authentication -git branch -d feature/user-authentication - -# Start release -git checkout develop -git checkout -b release/1.2.0 -# Version bump and changelog updates -git commit -am "Bump version to 1.2.0" - -# Finish release -git checkout main -git merge --no-ff release/1.2.0 -git tag -a v1.2.0 -m "Release version 1.2.0" -git checkout develop -git merge --no-ff release/1.2.0 -git branch -d release/1.2.0 - -# Hotfix -git checkout main -git checkout -b hotfix/security-patch -# Fix the issue -git commit -am "Fix security vulnerability" -git checkout main -git merge --no-ff hotfix/security-patch -git tag -a v1.2.1 -m "Hotfix version 1.2.1" -git checkout develop -git merge --no-ff hotfix/security-patch -``` - -## GitHub Flow - -### Structure -``` -main ← feature/user-auth - ← feature/payment-api - ← hotfix/critical-fix -``` - -### Branch Types -- **main**: Production-ready code, deployed automatically -- **feature/***: All changes, regardless of size or type - -### Typical Flow -1. Create feature branch from main: `git checkout -b feature/login main` -2. Work on feature with regular commits and pushes -3. Open pull request when ready for feedback -4. Deploy feature branch to staging for testing -5. Merge to main when approved and tested -6. Deploy main to production automatically -7. Delete feature branch - -### Advantages -- **Simple workflow** with only two branch types -- **Fast deployment** with minimal process overhead -- **Continuous integration** with frequent merges to main -- **Early feedback** through pull request reviews -- **Deploy from branches** allows testing before merge -- **Good for continuous deployment** - -### Disadvantages -- **Main can be unstable** if testing is insufficient -- **No release branches** for coordinating multiple features -- **Limited hotfix process** requires careful coordination -- **Requires strong testing** and CI/CD infrastructure -- **Not suitable for scheduled releases** -- **Can be chaotic** with many simultaneous features - -### Best For -- Small to medium teams (2-10 developers) -- Web applications with continuous deployment -- Products with rapid iteration cycles -- Teams with strong testing and CI/CD practices -- Projects where main is always deployable - -### Example Commands -```bash -# Start new feature -git checkout main -git pull origin main -git checkout -b feature/user-authentication - -# Regular work -git add . -git commit -m "feat(auth): add login form validation" -git push origin feature/user-authentication - -# Deploy branch for testing -# (Usually done through CI/CD) -./deploy.sh feature/user-authentication staging - -# Merge when ready -git checkout main -git merge feature/user-authentication -git push origin main -git branch -d feature/user-authentication - -# Automatic deployment to production -# (Triggered by push to main) -``` - -## Trunk-based Development - -### Structure -``` -main ← short-feature-branch (1-3 days max) - ← another-short-branch - ← direct-commits -``` - -### Branch Types -- **main**: The single source of truth, always deployable -- **Short-lived branches**: Optional, for changes taking >1 day - -### Typical Flow -1. Commit directly to main for small changes -2. Create short-lived branch for larger changes (max 2-3 days) -3. Merge to main frequently (multiple times per day) -4. Use feature flags to hide incomplete features -5. Deploy main to production multiple times per day -6. Release by enabling feature flags, not code deployment - -### Advantages -- **Simplest workflow** with minimal branching -- **Fastest integration** with continuous merges -- **Reduced merge conflicts** from short-lived branches -- **Always deployable main** through feature flags -- **Fastest feedback loop** with immediate integration -- **Excellent for CI/CD** and DevOps practices - -### Disadvantages -- **Requires discipline** to keep main stable -- **Needs feature flags** for incomplete features -- **Limited code review** for direct commits -- **Can be destabilizing** without proper testing -- **Requires advanced CI/CD** infrastructure -- **Not suitable for teams** uncomfortable with frequent changes - -### Best For -- Expert teams with strong DevOps culture -- Products requiring very fast iteration -- Microservices architectures -- Teams practicing continuous deployment -- Organizations with mature testing practices - -### Example Commands -```bash -# Small change - direct to main -git checkout main -git pull origin main -# Make changes -git add . -git commit -m "fix(ui): resolve button alignment issue" -git push origin main - -# Larger change - short branch -git checkout main -git pull origin main -git checkout -b payment-integration -# Work for 1-2 days maximum -git add . -git commit -m "feat(payment): add Stripe integration" -git push origin payment-integration - -# Immediate merge -git checkout main -git merge payment-integration -git push origin main -git branch -d payment-integration - -# Feature flag usage -if (featureFlags.enabled('stripe_payments', userId)) { - return renderStripePayment(); -} else { - return renderLegacyPayment(); -} -``` - -## Feature Comparison Matrix - -| Aspect | Git Flow | GitHub Flow | Trunk-based | -|--------|----------|-------------|-------------| -| **Complexity** | High | Medium | Low | -| **Learning Curve** | Steep | Moderate | Gentle | -| **Deployment Frequency** | Weekly/Monthly | Daily | Multiple/day | -| **Branch Lifetime** | Weeks/Months | Days/Weeks | Hours/Days | -| **Main Stability** | Very High | High | High* | -| **Release Coordination** | Excellent | Limited | Feature Flags | -| **Hotfix Support** | Built-in | Manual | Direct | -| **Merge Conflicts** | High | Medium | Low | -| **Team Size** | 10+ | 3-10 | Any | -| **CI/CD Requirements** | Medium | High | Very High | - -*With proper feature flags and testing - -## Release Strategies by Workflow - -### Git Flow Releases -```bash -# Scheduled release every 2 weeks -git checkout develop -git checkout -b release/2.3.0 - -# Version management -echo "2.3.0" > VERSION -npm version 2.3.0 --no-git-tag-version -python setup.py --version 2.3.0 - -# Changelog generation -git log --oneline release/2.2.0..HEAD --pretty=format:"%s" > CHANGELOG_DRAFT.md - -# Testing and bug fixes in release branch -git commit -am "fix: resolve issue found in release testing" - -# Finalize release -git checkout main -git merge --no-ff release/2.3.0 -git tag -a v2.3.0 -m "Release 2.3.0" - -# Deploy tagged version -docker build -t app:2.3.0 . -kubectl set image deployment/app app=app:2.3.0 -``` - -### GitHub Flow Releases -```bash -# Deploy every merge to main -git checkout main -git merge feature/new-payment-method - -# Automatic deployment via CI/CD -# .github/workflows/deploy.yml triggers on push to main - -# Tag releases for tracking (optional) -git tag -a v2.3.$(date +%Y%m%d%H%M) -m "Production deployment" - -# Rollback if needed -git revert HEAD -git push origin main # Triggers automatic rollback deployment -``` - -### Trunk-based Releases -```bash -# Continuous deployment with feature flags -git checkout main -git add feature_flags.json -git commit -m "feat: enable new payment method for 10% of users" -git push origin main - -# Gradual rollout -curl -X POST api/feature-flags/payment-v2/rollout/25 # 25% of users -# Monitor metrics... -curl -X POST api/feature-flags/payment-v2/rollout/50 # 50% of users -# Monitor metrics... -curl -X POST api/feature-flags/payment-v2/rollout/100 # Full rollout - -# Remove flag after successful rollout -git rm old_payment_code.js -git commit -m "cleanup: remove legacy payment code" -``` - -## Choosing the Right Workflow - -### Decision Matrix - -**Choose Git Flow if:** -- ✅ Team size > 10 developers -- ✅ Scheduled release cycles (weekly/monthly) -- ✅ Multiple versions supported simultaneously -- ✅ Formal testing and QA processes -- ✅ Complex enterprise software -- ❌ Need rapid deployment -- ❌ Small team or startup - -**Choose GitHub Flow if:** -- ✅ Team size 3-10 developers -- ✅ Web applications or APIs -- ✅ Strong CI/CD and testing -- ✅ Daily or continuous deployment -- ✅ Simple release requirements -- ❌ Complex release coordination needed -- ❌ Multiple release branches required - -**Choose Trunk-based Development if:** -- ✅ Expert development team -- ✅ Mature DevOps practices -- ✅ Microservices architecture -- ✅ Feature flag infrastructure -- ✅ Multiple deployments per day -- ✅ Strong automated testing -- ❌ Junior developers -- ❌ Complex integration requirements - -### Migration Strategies - -#### From Git Flow to GitHub Flow -1. **Simplify branching**: Eliminate develop branch, work directly with main -2. **Increase deployment frequency**: Move from scheduled to continuous releases -3. **Strengthen testing**: Improve automated test coverage and CI/CD -4. **Reduce branch lifetime**: Limit feature branches to 1-2 weeks maximum -5. **Train team**: Educate on simpler workflow and increased responsibility - -#### From GitHub Flow to Trunk-based -1. **Implement feature flags**: Add feature toggle infrastructure -2. **Improve CI/CD**: Ensure all tests run in <10 minutes -3. **Increase commit frequency**: Encourage multiple commits per day -4. **Reduce branch usage**: Start committing small changes directly to main -5. **Monitor stability**: Ensure main remains deployable at all times - -#### From Trunk-based to Git Flow -1. **Add structure**: Introduce develop and release branches -2. **Reduce deployment frequency**: Move to scheduled release cycles -3. **Extend branch lifetime**: Allow longer feature development cycles -4. **Formalize process**: Add approval gates and testing phases -5. **Coordinate releases**: Plan features for specific release versions - -## Anti-patterns to Avoid - -### Git Flow Anti-patterns -- **Long-lived feature branches** (>2 weeks) -- **Skipping release branches** for small releases -- **Direct commits to main** bypassing develop -- **Forgetting to merge back** to develop after hotfixes -- **Complex merge conflicts** from delayed integration - -### GitHub Flow Anti-patterns -- **Unstable main branch** due to insufficient testing -- **Long-lived feature branches** defeating the purpose -- **Skipping pull request reviews** for speed -- **Direct production deployment** without staging validation -- **No rollback plan** when deployments fail - -### Trunk-based Anti-patterns -- **Committing broken code** to main branch -- **Feature branches lasting weeks** defeating the philosophy -- **No feature flags** for incomplete features -- **Insufficient automated testing** leading to instability -- **Poor CI/CD pipeline** causing deployment delays - -## Conclusion - -The choice of release workflow significantly impacts your team's productivity, code quality, and deployment reliability. Consider your team size, technical maturity, deployment requirements, and organizational culture when making this decision. - -**Start conservative** (Git Flow) and evolve toward more agile approaches (GitHub Flow, Trunk-based) as your team's skills and infrastructure mature. The key is consistency within your team and alignment with your organization's goals and constraints. - -Remember: **The best workflow is the one your team can execute consistently and reliably**. \ No newline at end of file diff --git a/engineering/skills/release-manager/release_planner.py b/engineering/skills/release-manager/release_planner.py deleted file mode 100644 index 93f2f249..00000000 --- a/engineering/skills/release-manager/release_planner.py +++ /dev/null @@ -1,1003 +0,0 @@ -#!/usr/bin/env python3 -""" -Release Planner - -Takes a list of features/PRs/tickets planned for release and assesses release readiness. -Checks for required approvals, test coverage thresholds, breaking change documentation, -dependency updates, migration steps needed. Generates release checklist, communication -plan, and rollback procedures. - -Input: release plan JSON (features, PRs, target date) -Output: release readiness report + checklist + rollback runbook + announcement draft -""" - -import argparse -import json -import sys -from datetime import datetime, timedelta -from typing import Dict, List, Optional, Any, Union -from dataclasses import dataclass, asdict -from enum import Enum - - -class RiskLevel(Enum): - """Risk levels for release components.""" - LOW = "low" - MEDIUM = "medium" - HIGH = "high" - CRITICAL = "critical" - - -class ComponentStatus(Enum): - """Status of release components.""" - PENDING = "pending" - IN_PROGRESS = "in_progress" - READY = "ready" - BLOCKED = "blocked" - FAILED = "failed" - - -@dataclass -class Feature: - """Represents a feature in the release.""" - id: str - title: str - description: str - type: str # feature, bugfix, security, breaking_change, etc. - assignee: str - status: ComponentStatus - pull_request_url: Optional[str] = None - issue_url: Optional[str] = None - risk_level: RiskLevel = RiskLevel.MEDIUM - test_coverage_required: float = 80.0 - test_coverage_actual: Optional[float] = None - requires_migration: bool = False - migration_complexity: str = "simple" # simple, moderate, complex - breaking_changes: List[str] = None - dependencies: List[str] = None - qa_approved: bool = False - security_approved: bool = False - pm_approved: bool = False - - def __post_init__(self): - if self.breaking_changes is None: - self.breaking_changes = [] - if self.dependencies is None: - self.dependencies = [] - - -@dataclass -class QualityGate: - """Quality gate requirements.""" - name: str - required: bool - status: ComponentStatus - details: Optional[str] = None - threshold: Optional[float] = None - actual_value: Optional[float] = None - - -@dataclass -class Stakeholder: - """Stakeholder for release communication.""" - name: str - role: str - contact: str - notification_type: str # email, slack, teams - critical_path: bool = False - - -@dataclass -class RollbackStep: - """Individual rollback step.""" - order: int - description: str - command: Optional[str] = None - estimated_time: str = "5 minutes" - risk_level: RiskLevel = RiskLevel.LOW - verification: str = "" - - -class ReleasePlanner: - """Main release planning and assessment logic.""" - - def __init__(self): - self.release_name: str = "" - self.version: str = "" - self.target_date: Optional[datetime] = None - self.features: List[Feature] = [] - self.quality_gates: List[QualityGate] = [] - self.stakeholders: List[Stakeholder] = [] - self.rollback_steps: List[RollbackStep] = [] - - # Configuration - self.min_test_coverage = 80.0 - self.required_approvals = ['pm_approved', 'qa_approved'] - self.high_risk_approval_requirements = ['pm_approved', 'qa_approved', 'security_approved'] - - def load_release_plan(self, plan_data: Union[str, Dict]): - """Load release plan from JSON.""" - if isinstance(plan_data, str): - data = json.loads(plan_data) - else: - data = plan_data - - self.release_name = data.get('release_name', 'Unnamed Release') - self.version = data.get('version', '1.0.0') - - if 'target_date' in data: - self.target_date = datetime.fromisoformat(data['target_date'].replace('Z', '+00:00')) - - # Load features - self.features = [] - for feature_data in data.get('features', []): - try: - status = ComponentStatus(feature_data.get('status', 'pending')) - risk_level = RiskLevel(feature_data.get('risk_level', 'medium')) - - feature = Feature( - id=feature_data['id'], - title=feature_data['title'], - description=feature_data.get('description', ''), - type=feature_data.get('type', 'feature'), - assignee=feature_data.get('assignee', ''), - status=status, - pull_request_url=feature_data.get('pull_request_url'), - issue_url=feature_data.get('issue_url'), - risk_level=risk_level, - test_coverage_required=feature_data.get('test_coverage_required', 80.0), - test_coverage_actual=feature_data.get('test_coverage_actual'), - requires_migration=feature_data.get('requires_migration', False), - migration_complexity=feature_data.get('migration_complexity', 'simple'), - breaking_changes=feature_data.get('breaking_changes', []), - dependencies=feature_data.get('dependencies', []), - qa_approved=feature_data.get('qa_approved', False), - security_approved=feature_data.get('security_approved', False), - pm_approved=feature_data.get('pm_approved', False) - ) - self.features.append(feature) - except Exception as e: - print(f"Warning: Error parsing feature {feature_data.get('id', 'unknown')}: {e}", - file=sys.stderr) - - # Load quality gates - self.quality_gates = [] - for gate_data in data.get('quality_gates', []): - try: - status = ComponentStatus(gate_data.get('status', 'pending')) - gate = QualityGate( - name=gate_data['name'], - required=gate_data.get('required', True), - status=status, - details=gate_data.get('details'), - threshold=gate_data.get('threshold'), - actual_value=gate_data.get('actual_value') - ) - self.quality_gates.append(gate) - except Exception as e: - print(f"Warning: Error parsing quality gate {gate_data.get('name', 'unknown')}: {e}", - file=sys.stderr) - - # Load stakeholders - self.stakeholders = [] - for stakeholder_data in data.get('stakeholders', []): - stakeholder = Stakeholder( - name=stakeholder_data['name'], - role=stakeholder_data['role'], - contact=stakeholder_data['contact'], - notification_type=stakeholder_data.get('notification_type', 'email'), - critical_path=stakeholder_data.get('critical_path', False) - ) - self.stakeholders.append(stakeholder) - - # Load or generate default quality gates if none provided - if not self.quality_gates: - self._generate_default_quality_gates() - - # Load or generate default rollback steps - if 'rollback_steps' in data: - self.rollback_steps = [] - for step_data in data['rollback_steps']: - risk_level = RiskLevel(step_data.get('risk_level', 'low')) - step = RollbackStep( - order=step_data['order'], - description=step_data['description'], - command=step_data.get('command'), - estimated_time=step_data.get('estimated_time', '5 minutes'), - risk_level=risk_level, - verification=step_data.get('verification', '') - ) - self.rollback_steps.append(step) - else: - self._generate_default_rollback_steps() - - def _generate_default_quality_gates(self): - """Generate default quality gates.""" - default_gates = [ - { - 'name': 'Unit Test Coverage', - 'required': True, - 'threshold': self.min_test_coverage, - 'details': f'Minimum {self.min_test_coverage}% code coverage required' - }, - { - 'name': 'Integration Tests', - 'required': True, - 'details': 'All integration tests must pass' - }, - { - 'name': 'Security Scan', - 'required': True, - 'details': 'No high or critical security vulnerabilities' - }, - { - 'name': 'Performance Testing', - 'required': True, - 'details': 'Performance metrics within acceptable thresholds' - }, - { - 'name': 'Documentation Review', - 'required': True, - 'details': 'API docs and user docs updated for new features' - }, - { - 'name': 'Dependency Audit', - 'required': True, - 'details': 'All dependencies scanned for vulnerabilities' - } - ] - - self.quality_gates = [] - for gate_data in default_gates: - gate = QualityGate( - name=gate_data['name'], - required=gate_data['required'], - status=ComponentStatus.PENDING, - details=gate_data['details'], - threshold=gate_data.get('threshold') - ) - self.quality_gates.append(gate) - - def _generate_default_rollback_steps(self): - """Generate default rollback procedure.""" - default_steps = [ - { - 'order': 1, - 'description': 'Alert on-call team and stakeholders', - 'estimated_time': '2 minutes', - 'verification': 'Confirm team is aware and responding' - }, - { - 'order': 2, - 'description': 'Switch load balancer to previous version', - 'command': 'kubectl patch service app --patch \'{"spec": {"selector": {"version": "previous"}}}\'', - 'estimated_time': '30 seconds', - 'verification': 'Check that traffic is routing to old version' - }, - { - 'order': 3, - 'description': 'Verify application health after rollback', - 'estimated_time': '5 minutes', - 'verification': 'Check error rates, response times, and health endpoints' - }, - { - 'order': 4, - 'description': 'Roll back database migrations if needed', - 'command': 'python manage.py migrate app 0001', - 'estimated_time': '10 minutes', - 'risk_level': 'high', - 'verification': 'Verify data integrity and application functionality' - }, - { - 'order': 5, - 'description': 'Update monitoring dashboards and alerts', - 'estimated_time': '5 minutes', - 'verification': 'Confirm metrics reflect rollback state' - }, - { - 'order': 6, - 'description': 'Notify stakeholders of successful rollback', - 'estimated_time': '5 minutes', - 'verification': 'All stakeholders acknowledge rollback completion' - } - ] - - self.rollback_steps = [] - for step_data in default_steps: - risk_level = RiskLevel(step_data.get('risk_level', 'low')) - step = RollbackStep( - order=step_data['order'], - description=step_data['description'], - command=step_data.get('command'), - estimated_time=step_data.get('estimated_time', '5 minutes'), - risk_level=risk_level, - verification=step_data.get('verification', '') - ) - self.rollback_steps.append(step) - - def assess_release_readiness(self) -> Dict: - """Assess overall release readiness.""" - assessment = { - 'overall_status': 'ready', - 'readiness_score': 0.0, - 'blocking_issues': [], - 'warnings': [], - 'recommendations': [], - 'feature_summary': {}, - 'quality_gate_summary': {}, - 'timeline_assessment': {} - } - - total_score = 0 - max_score = 0 - - # Assess features - feature_stats = { - 'total': len(self.features), - 'ready': 0, - 'blocked': 0, - 'in_progress': 0, - 'pending': 0, - 'high_risk': 0, - 'breaking_changes': 0, - 'missing_approvals': 0, - 'low_test_coverage': 0 - } - - for feature in self.features: - max_score += 10 # Each feature worth 10 points - - if feature.status == ComponentStatus.READY: - feature_stats['ready'] += 1 - total_score += 10 - elif feature.status == ComponentStatus.BLOCKED: - feature_stats['blocked'] += 1 - assessment['blocking_issues'].append( - f"Feature '{feature.title}' ({feature.id}) is blocked" - ) - elif feature.status == ComponentStatus.IN_PROGRESS: - feature_stats['in_progress'] += 1 - total_score += 5 # Partial credit - assessment['warnings'].append( - f"Feature '{feature.title}' ({feature.id}) still in progress" - ) - else: - feature_stats['pending'] += 1 - assessment['warnings'].append( - f"Feature '{feature.title}' ({feature.id}) is pending" - ) - - # Check risk level - if feature.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]: - feature_stats['high_risk'] += 1 - - # Check breaking changes - if feature.breaking_changes: - feature_stats['breaking_changes'] += 1 - - # Check approvals - missing_approvals = self._check_feature_approvals(feature) - if missing_approvals: - feature_stats['missing_approvals'] += 1 - assessment['blocking_issues'].append( - f"Feature '{feature.title}' missing approvals: {', '.join(missing_approvals)}" - ) - - # Check test coverage - if (feature.test_coverage_actual is not None and - feature.test_coverage_actual < feature.test_coverage_required): - feature_stats['low_test_coverage'] += 1 - assessment['warnings'].append( - f"Feature '{feature.title}' has low test coverage: " - f"{feature.test_coverage_actual}% < {feature.test_coverage_required}%" - ) - - assessment['feature_summary'] = feature_stats - - # Assess quality gates - gate_stats = { - 'total': len(self.quality_gates), - 'passed': 0, - 'failed': 0, - 'pending': 0, - 'required_failed': 0 - } - - for gate in self.quality_gates: - max_score += 5 # Each gate worth 5 points - - if gate.status == ComponentStatus.READY: - gate_stats['passed'] += 1 - total_score += 5 - elif gate.status == ComponentStatus.FAILED: - gate_stats['failed'] += 1 - if gate.required: - gate_stats['required_failed'] += 1 - assessment['blocking_issues'].append( - f"Required quality gate '{gate.name}' failed" - ) - else: - gate_stats['pending'] += 1 - if gate.required: - assessment['warnings'].append( - f"Required quality gate '{gate.name}' is pending" - ) - - assessment['quality_gate_summary'] = gate_stats - - # Timeline assessment - if self.target_date: - # Handle timezone-aware datetime comparison - now = datetime.now(self.target_date.tzinfo) if self.target_date.tzinfo else datetime.now() - days_until_release = (self.target_date - now).days - assessment['timeline_assessment'] = { - 'target_date': self.target_date.isoformat(), - 'days_remaining': days_until_release, - 'timeline_status': 'on_track' if days_until_release > 0 else 'overdue' - } - - if days_until_release < 0: - assessment['blocking_issues'].append(f"Release is {abs(days_until_release)} days overdue") - elif days_until_release < 3 and feature_stats['blocked'] > 0: - assessment['blocking_issues'].append("Not enough time to resolve blocked features") - - # Calculate overall readiness score - if max_score > 0: - assessment['readiness_score'] = (total_score / max_score) * 100 - - # Determine overall status - if assessment['blocking_issues']: - assessment['overall_status'] = 'blocked' - elif assessment['warnings']: - assessment['overall_status'] = 'at_risk' - else: - assessment['overall_status'] = 'ready' - - # Generate recommendations - if feature_stats['missing_approvals'] > 0: - assessment['recommendations'].append("Obtain required approvals for pending features") - - if feature_stats['low_test_coverage'] > 0: - assessment['recommendations'].append("Improve test coverage for features below threshold") - - if gate_stats['pending'] > 0: - assessment['recommendations'].append("Complete pending quality gate validations") - - if feature_stats['high_risk'] > 0: - assessment['recommendations'].append("Review high-risk features for additional validation") - - return assessment - - def _check_feature_approvals(self, feature: Feature) -> List[str]: - """Check which approvals are missing for a feature.""" - missing = [] - - # Determine required approvals based on risk level - required = self.required_approvals.copy() - if feature.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]: - required = self.high_risk_approval_requirements.copy() - - if 'pm_approved' in required and not feature.pm_approved: - missing.append('PM approval') - - if 'qa_approved' in required and not feature.qa_approved: - missing.append('QA approval') - - if 'security_approved' in required and not feature.security_approved: - missing.append('Security approval') - - return missing - - def generate_release_checklist(self) -> List[Dict]: - """Generate comprehensive release checklist.""" - checklist = [] - - # Pre-release validation - checklist.extend([ - { - 'category': 'Pre-Release Validation', - 'item': 'All features implemented and tested', - 'status': 'ready' if all(f.status == ComponentStatus.READY for f in self.features) else 'pending', - 'details': f"{len([f for f in self.features if f.status == ComponentStatus.READY])}/{len(self.features)} features ready" - }, - { - 'category': 'Pre-Release Validation', - 'item': 'Breaking changes documented', - 'status': 'ready' if self._check_breaking_change_docs() else 'pending', - 'details': f"{len([f for f in self.features if f.breaking_changes])} features have breaking changes" - }, - { - 'category': 'Pre-Release Validation', - 'item': 'Migration scripts tested', - 'status': 'ready' if self._check_migrations() else 'pending', - 'details': f"{len([f for f in self.features if f.requires_migration])} features require migrations" - } - ]) - - # Quality gates - for gate in self.quality_gates: - checklist.append({ - 'category': 'Quality Gates', - 'item': gate.name, - 'status': gate.status.value, - 'details': gate.details, - 'required': gate.required - }) - - # Approvals - approval_items = [ - ('Product Manager sign-off', self._check_pm_approvals()), - ('QA validation complete', self._check_qa_approvals()), - ('Security team clearance', self._check_security_approvals()) - ] - - for item, status in approval_items: - checklist.append({ - 'category': 'Approvals', - 'item': item, - 'status': 'ready' if status else 'pending' - }) - - # Documentation - doc_items = [ - 'CHANGELOG.md updated', - 'API documentation updated', - 'User documentation updated', - 'Migration guide written', - 'Rollback procedure documented' - ] - - for item in doc_items: - checklist.append({ - 'category': 'Documentation', - 'item': item, - 'status': 'pending' # Would need integration with docs system to check - }) - - # Deployment preparation - deployment_items = [ - 'Database migrations prepared', - 'Environment variables configured', - 'Monitoring alerts updated', - 'Rollback plan tested', - 'Stakeholders notified' - ] - - for item in deployment_items: - checklist.append({ - 'category': 'Deployment', - 'item': item, - 'status': 'pending' - }) - - return checklist - - def _check_breaking_change_docs(self) -> bool: - """Check if breaking changes are properly documented.""" - features_with_breaking_changes = [f for f in self.features if f.breaking_changes] - return all(len(f.breaking_changes) > 0 for f in features_with_breaking_changes) - - def _check_migrations(self) -> bool: - """Check migration readiness.""" - features_with_migrations = [f for f in self.features if f.requires_migration] - return all(f.status == ComponentStatus.READY for f in features_with_migrations) - - def _check_pm_approvals(self) -> bool: - """Check PM approvals.""" - return all(f.pm_approved for f in self.features if f.risk_level != RiskLevel.LOW) - - def _check_qa_approvals(self) -> bool: - """Check QA approvals.""" - return all(f.qa_approved for f in self.features) - - def _check_security_approvals(self) -> bool: - """Check security approvals.""" - high_risk_features = [f for f in self.features if f.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL]] - return all(f.security_approved for f in high_risk_features) - - def generate_communication_plan(self) -> Dict: - """Generate stakeholder communication plan.""" - plan = { - 'internal_notifications': [], - 'external_notifications': [], - 'timeline': [], - 'channels': {}, - 'templates': {} - } - - # Group stakeholders by type - internal_stakeholders = [s for s in self.stakeholders if s.role in - ['developer', 'qa', 'pm', 'devops', 'security']] - external_stakeholders = [s for s in self.stakeholders if s.role in - ['customer', 'partner', 'support']] - - # Internal notifications - for stakeholder in internal_stakeholders: - plan['internal_notifications'].append({ - 'recipient': stakeholder.name, - 'role': stakeholder.role, - 'method': stakeholder.notification_type, - 'content_type': 'technical_details', - 'timing': 'T-24h and T-0' - }) - - # External notifications - for stakeholder in external_stakeholders: - plan['external_notifications'].append({ - 'recipient': stakeholder.name, - 'role': stakeholder.role, - 'method': stakeholder.notification_type, - 'content_type': 'user_facing_changes', - 'timing': 'T-48h and T+1h' - }) - - # Communication timeline - if self.target_date: - timeline_items = [ - (timedelta(days=-2), 'Send pre-release notification to external stakeholders'), - (timedelta(days=-1), 'Send deployment notification to internal teams'), - (timedelta(hours=-2), 'Final go/no-go decision'), - (timedelta(hours=0), 'Begin deployment'), - (timedelta(hours=1), 'Post-deployment status update'), - (timedelta(hours=24), 'Post-release summary') - ] - - for delta, description in timeline_items: - notification_time = self.target_date + delta - plan['timeline'].append({ - 'time': notification_time.isoformat(), - 'description': description, - 'recipients': 'all' if 'all' in description.lower() else 'internal' - }) - - # Communication channels - channels = {} - for stakeholder in self.stakeholders: - if stakeholder.notification_type not in channels: - channels[stakeholder.notification_type] = [] - channels[stakeholder.notification_type].append(stakeholder.contact) - plan['channels'] = channels - - # Message templates - plan['templates'] = self._generate_message_templates() - - return plan - - def _generate_message_templates(self) -> Dict: - """Generate message templates for different audiences.""" - breaking_changes = [f for f in self.features if f.breaking_changes] - new_features = [f for f in self.features if f.type == 'feature'] - bug_fixes = [f for f in self.features if f.type == 'bugfix'] - - templates = { - 'internal_pre_release': { - 'subject': f'Release {self.version} - Pre-deployment Notification', - 'body': f"""Team, - -We are preparing to deploy {self.release_name} version {self.version} on {self.target_date.strftime('%Y-%m-%d %H:%M UTC') if self.target_date else 'TBD'}. - -Key Changes: -- {len(new_features)} new features -- {len(bug_fixes)} bug fixes -- {len(breaking_changes)} breaking changes - -Please review the release notes and prepare for any needed support activities. - -Rollback plan: Available in release documentation -On-call: Please be available during deployment window - -Best regards, -Release Team""" - }, - 'external_user_notification': { - 'subject': f'Product Update - Version {self.version} Now Available', - 'body': f"""Dear Users, - -We're excited to announce version {self.version} of {self.release_name} is now available! - -What's New: -{chr(10).join(f"- {f.title}" for f in new_features[:5])} - -Bug Fixes: -{chr(10).join(f"- {f.title}" for f in bug_fixes[:3])} - -{'Important: This release includes breaking changes. Please review the migration guide.' if breaking_changes else ''} - -For full release notes and migration instructions, visit our documentation. - -Thank you for using our product! - -The Development Team""" - }, - 'rollback_notification': { - 'subject': f'URGENT: Release {self.version} Rollback Initiated', - 'body': f"""ATTENTION: Release rollback in progress. - -Release: {self.version} -Reason: [TO BE FILLED] -Rollback initiated: {datetime.now().strftime('%Y-%m-%d %H:%M UTC')} -Estimated completion: [TO BE FILLED] - -Current status: Rolling back to previous stable version -Impact: [TO BE FILLED] - -We will provide updates every 15 minutes until rollback is complete. - -Incident Commander: [TO BE FILLED] -Status page: [TO BE FILLED]""" - } - } - - return templates - - def generate_rollback_runbook(self) -> Dict: - """Generate detailed rollback runbook.""" - runbook = { - 'overview': { - 'purpose': f'Emergency rollback procedure for {self.release_name} v{self.version}', - 'triggers': [ - 'Error rate spike (>2x baseline for >15 minutes)', - 'Critical functionality failure', - 'Security incident', - 'Data corruption detected', - 'Performance degradation (>50% latency increase)', - 'Manual decision by incident commander' - ], - 'decision_makers': ['On-call Engineer', 'Engineering Lead', 'Incident Commander'], - 'estimated_total_time': self._calculate_rollback_time() - }, - 'prerequisites': [ - 'Confirm rollback is necessary (check with incident commander)', - 'Notify stakeholders of rollback decision', - 'Ensure database backups are available', - 'Verify monitoring systems are operational', - 'Have communication channels ready' - ], - 'steps': [], - 'verification': { - 'health_checks': [ - 'Application responds to health endpoint', - 'Database connectivity confirmed', - 'Authentication system functional', - 'Core user workflows working', - 'Error rates back to baseline', - 'Performance metrics within normal range' - ], - 'rollback_confirmation': [ - 'Previous version fully deployed', - 'Database in consistent state', - 'All services communicating properly', - 'Monitoring shows stable metrics', - 'Sample user workflows tested' - ] - }, - 'post_rollback': [ - 'Update status page with resolution', - 'Notify all stakeholders of successful rollback', - 'Schedule post-incident review', - 'Document issues encountered during rollback', - 'Plan investigation of root cause', - 'Determine timeline for next release attempt' - ], - 'emergency_contacts': [] - } - - # Convert rollback steps to detailed format - for step in sorted(self.rollback_steps, key=lambda x: x.order): - step_data = { - 'order': step.order, - 'title': step.description, - 'estimated_time': step.estimated_time, - 'risk_level': step.risk_level.value, - 'instructions': step.description, - 'command': step.command, - 'verification': step.verification, - 'rollback_possible': step.risk_level != RiskLevel.CRITICAL - } - runbook['steps'].append(step_data) - - # Add emergency contacts - critical_stakeholders = [s for s in self.stakeholders if s.critical_path] - for stakeholder in critical_stakeholders: - runbook['emergency_contacts'].append({ - 'name': stakeholder.name, - 'role': stakeholder.role, - 'contact': stakeholder.contact, - 'method': stakeholder.notification_type - }) - - return runbook - - def _calculate_rollback_time(self) -> str: - """Calculate estimated total rollback time.""" - total_minutes = 0 - for step in self.rollback_steps: - # Parse time estimates like "5 minutes", "30 seconds", "1 hour" - time_str = step.estimated_time.lower() - if 'minute' in time_str: - minutes = int(re.search(r'(\d+)', time_str).group(1)) - total_minutes += minutes - elif 'hour' in time_str: - hours = int(re.search(r'(\d+)', time_str).group(1)) - total_minutes += hours * 60 - elif 'second' in time_str: - # Round up seconds to minutes - total_minutes += 1 - - if total_minutes < 60: - return f"{total_minutes} minutes" - else: - hours = total_minutes // 60 - minutes = total_minutes % 60 - return f"{hours}h {minutes}m" - - -def main(): - """Main CLI entry point.""" - parser = argparse.ArgumentParser(description="Assess release readiness and generate release plans") - parser.add_argument('--input', '-i', required=True, - help='Release plan JSON file') - parser.add_argument('--output-format', '-f', - choices=['json', 'markdown', 'text'], - default='text', help='Output format') - parser.add_argument('--output', '-o', type=str, - help='Output file (default: stdout)') - parser.add_argument('--include-checklist', action='store_true', - help='Include release checklist in output') - parser.add_argument('--include-communication', action='store_true', - help='Include communication plan') - parser.add_argument('--include-rollback', action='store_true', - help='Include rollback runbook') - parser.add_argument('--min-coverage', type=float, default=80.0, - help='Minimum test coverage threshold') - - args = parser.parse_args() - - # Load release plan - try: - with open(args.input, 'r', encoding='utf-8') as f: - plan_data = f.read() - except Exception as e: - print(f"Error reading input file: {e}", file=sys.stderr) - sys.exit(1) - - # Initialize planner - planner = ReleasePlanner() - planner.min_test_coverage = args.min_coverage - - try: - planner.load_release_plan(plan_data) - except Exception as e: - print(f"Error loading release plan: {e}", file=sys.stderr) - sys.exit(1) - - # Generate assessment - assessment = planner.assess_release_readiness() - - # Generate optional components - checklist = planner.generate_release_checklist() if args.include_checklist else None - communication = planner.generate_communication_plan() if args.include_communication else None - rollback = planner.generate_rollback_runbook() if args.include_rollback else None - - # Generate output - if args.output_format == 'json': - output_data = { - 'assessment': assessment, - 'checklist': checklist, - 'communication_plan': communication, - 'rollback_runbook': rollback - } - output_text = json.dumps(output_data, indent=2, default=str) - - elif args.output_format == 'markdown': - output_lines = [ - f"# Release Readiness Report - {planner.release_name} v{planner.version}", - "", - f"**Overall Status:** {assessment['overall_status'].upper()}", - f"**Readiness Score:** {assessment['readiness_score']:.1f}%", - "" - ] - - if assessment['blocking_issues']: - output_lines.extend([ - "## 🚫 Blocking Issues", - "" - ]) - for issue in assessment['blocking_issues']: - output_lines.append(f"- {issue}") - output_lines.append("") - - if assessment['warnings']: - output_lines.extend([ - "## ⚠️ Warnings", - "" - ]) - for warning in assessment['warnings']: - output_lines.append(f"- {warning}") - output_lines.append("") - - # Feature summary - fs = assessment['feature_summary'] - output_lines.extend([ - "## Features Summary", - "", - f"- **Total:** {fs['total']}", - f"- **Ready:** {fs['ready']}", - f"- **In Progress:** {fs['in_progress']}", - f"- **Blocked:** {fs['blocked']}", - f"- **Breaking Changes:** {fs['breaking_changes']}", - "" - ]) - - if checklist: - output_lines.extend([ - "## Release Checklist", - "" - ]) - current_category = "" - for item in checklist: - if item['category'] != current_category: - current_category = item['category'] - output_lines.append(f"### {current_category}") - output_lines.append("") - - status_icon = "✅" if item['status'] == 'ready' else "❌" if item['status'] == 'failed' else "⏳" - output_lines.append(f"- {status_icon} {item['item']}") - output_lines.append("") - - output_text = '\n'.join(output_lines) - - else: # text format - output_lines = [ - f"Release Readiness Report", - f"========================", - f"Release: {planner.release_name} v{planner.version}", - f"Status: {assessment['overall_status'].upper()}", - f"Readiness Score: {assessment['readiness_score']:.1f}%", - "" - ] - - if assessment['blocking_issues']: - output_lines.extend(["BLOCKING ISSUES:", ""]) - for issue in assessment['blocking_issues']: - output_lines.append(f" ❌ {issue}") - output_lines.append("") - - if assessment['warnings']: - output_lines.extend(["WARNINGS:", ""]) - for warning in assessment['warnings']: - output_lines.append(f" ⚠️ {warning}") - output_lines.append("") - - if assessment['recommendations']: - output_lines.extend(["RECOMMENDATIONS:", ""]) - for rec in assessment['recommendations']: - output_lines.append(f" 💡 {rec}") - output_lines.append("") - - # Summary stats - fs = assessment['feature_summary'] - gs = assessment['quality_gate_summary'] - - output_lines.extend([ - f"FEATURE SUMMARY:", - f" Total: {fs['total']} | Ready: {fs['ready']} | Blocked: {fs['blocked']}", - f" Breaking Changes: {fs['breaking_changes']} | Missing Approvals: {fs['missing_approvals']}", - "", - f"QUALITY GATES:", - f" Total: {gs['total']} | Passed: {gs['passed']} | Failed: {gs['failed']}", - "" - ]) - - output_text = '\n'.join(output_lines) - - # Write output - if args.output: - with open(args.output, 'w', encoding='utf-8') as f: - f.write(output_text) - else: - print(output_text) - - -if __name__ == '__main__': - main() \ No newline at end of file diff --git a/engineering/skills/skill-tester/SKILL.md b/engineering/skills/skill-tester/SKILL.md index 4a733ce0..84b24708 100644 --- a/engineering/skills/skill-tester/SKILL.md +++ b/engineering/skills/skill-tester/SKILL.md @@ -5,385 +5,88 @@ description: "Validate, test, and score the quality of skills within the claude- # Skill Tester ---- +**Tier**: POWERFUL · **Category**: Engineering Quality Assurance · **Dependencies**: None (Python stdlib only) -**Name**: skill-tester -**Tier**: POWERFUL -**Category**: Engineering Quality Assurance -**Dependencies**: None (Python Standard Library Only) -**Author**: Claude Skills Engineering Team -**Version**: 1.0.0 -**Last Updated**: 2026-02-16 +Meta-skill that validates, tests, and scores skills in this repository. Four tools, run from the **repo root** with full paths: ---- +1. **`scripts/skill_validator.py`** — structure + documentation compliance +2. **`scripts/script_tester.py`** — Python script syntax/imports/runtime/output testing +3. **`scripts/quality_scorer.py`** — multi-dimensional scoring with letter grade +4. **`scripts/security_scorer.py`** — security posture scoring (also available via `quality_scorer.py --include-security`) -## Description +> **Scope note:** this skill's tier line-count minimums measure *legacy* skills. For authoring *new* skills, `engineering/write-a-skill` (SKILL.md under ~100 lines, Matt Pocock doctrine) is the binding standard — do not pad a new skill to satisfy a tier minimum here. -The Skill Tester is a comprehensive meta-skill designed to validate, test, and score the quality of skills within the claude-skills ecosystem. This powerful quality assurance tool ensures that all skills meet the rigorous standards required for BASIC, STANDARD, and POWERFUL tier classifications through automated validation, testing, and scoring mechanisms. +## Quick Start (exact, runnable from repo root) -As the gatekeeping system for skill quality, this meta-skill provides three core capabilities: -1. **Structure Validation** - Ensures skills conform to required directory structures, file formats, and documentation standards -2. **Script Testing** - Validates Python scripts for syntax, imports, functionality, and output format compliance -3. **Quality Scoring** - Provides comprehensive quality assessment across multiple dimensions with letter grades and improvement recommendations - -This skill is essential for maintaining ecosystem consistency, enabling automated CI/CD integration, and supporting both manual and automated quality assurance workflows. It serves as the foundation for pre-commit hooks, pull request validation, and continuous integration processes that maintain the high-quality standards of the claude-skills repository. - -## Core Features - -### Comprehensive Skill Validation -- **Structure Compliance**: Validates directory structure, required files (SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/) -- **Documentation Standards**: Checks SKILL.md frontmatter, section completeness, minimum line counts per tier -- **File Format Validation**: Ensures proper Markdown formatting, YAML frontmatter syntax, and file naming conventions - -### Advanced Script Testing -- **Syntax Validation**: Compiles Python scripts to detect syntax errors before execution -- **Import Analysis**: Enforces standard library only policy, identifies external dependencies -- **Runtime Testing**: Executes scripts with sample data, validates argparse implementation, tests --help functionality -- **Output Format Compliance**: Verifies dual output support (JSON + human-readable), proper error handling - -### Multi-Dimensional Quality Scoring -- **Documentation Quality (25%)**: SKILL.md depth and completeness, README clarity, reference documentation quality -- **Code Quality (25%)**: Script complexity, error handling robustness, output format consistency, maintainability -- **Completeness (25%)**: Required directory presence, sample data adequacy, expected output verification -- **Usability (25%)**: Example clarity, argparse help text quality, installation simplicity, user experience - -### Tier Classification System -Automatically classifies skills based on complexity and functionality: - -#### BASIC Tier Requirements -- Minimum 100 lines in SKILL.md -- At least 1 Python script (100-300 LOC) -- Basic argparse implementation -- Simple input/output handling -- Essential documentation coverage - -#### STANDARD Tier Requirements -- Minimum 200 lines in SKILL.md -- 1-2 Python scripts (300-500 LOC each) -- Advanced argparse with subcommands -- JSON + text output formats -- Comprehensive examples and references -- Error handling and edge case management - -#### POWERFUL Tier Requirements -- Minimum 300 lines in SKILL.md -- 2-3 Python scripts (500-800 LOC each) -- Complex argparse with multiple modes -- Sophisticated output formatting and validation -- Extensive documentation and reference materials -- Advanced error handling and recovery mechanisms -- CI/CD integration capabilities - -## Architecture & Design - -### Modular Design Philosophy -The skill-tester follows a modular architecture where each component serves a specific validation purpose: - -- **skill_validator.py**: Core structural and documentation validation engine -- **script_tester.py**: Runtime testing and execution validation framework -- **quality_scorer.py**: Multi-dimensional quality assessment and scoring system - -### Standards Enforcement -All validation is performed against well-defined standards documented in the references/ directory: -- **Skill Structure Specification**: Defines mandatory and optional components -- **Tier Requirements Matrix**: Detailed requirements for each skill tier -- **Quality Scoring Rubric**: Comprehensive scoring methodology and weightings - -### Integration Capabilities -Designed for seamless integration into existing development workflows: -- **Pre-commit Hooks**: Prevents substandard skills from being committed -- **CI/CD Pipelines**: Automated quality gates in pull request workflows -- **Manual Validation**: Interactive command-line tools for development-time validation -- **Batch Processing**: Bulk validation and scoring of existing skill repositories - -## Implementation Details - -### skill_validator.py Core Functions -```python -# Primary validation workflow -validate_skill_structure() -> ValidationReport -check_skill_md_compliance() -> DocumentationReport -validate_python_scripts() -> ScriptReport -generate_compliance_score() -> float -``` - -Key validation checks include: -- SKILL.md frontmatter parsing and validation -- Required section presence (Description, Features, Usage, etc.) -- Minimum line count enforcement per tier -- Python script argparse implementation verification -- Standard library import enforcement -- Directory structure compliance -- README.md quality assessment - -### script_tester.py Testing Framework -```python -# Core testing functions -syntax_validation() -> SyntaxReport -import_validation() -> ImportReport -runtime_testing() -> RuntimeReport -output_format_validation() -> OutputReport -``` - -Testing capabilities encompass: -- Python AST-based syntax validation -- Import statement analysis and external dependency detection -- Controlled script execution with timeout protection -- Argparse --help functionality verification -- Sample data processing and output validation -- Expected output comparison and difference reporting - -### quality_scorer.py Scoring System -```python -# Multi-dimensional scoring -score_documentation() -> float # 25% weight -score_code_quality() -> float # 25% weight -score_completeness() -> float # 25% weight -score_usability() -> float # 25% weight -calculate_overall_grade() -> str # A-F grade -``` - -Scoring dimensions include: -- **Documentation**: Completeness, clarity, examples, reference quality -- **Code Quality**: Complexity, maintainability, error handling, output consistency -- **Completeness**: Required files, sample data, expected outputs, test coverage -- **Usability**: Help text quality, example clarity, installation simplicity - -## Usage Scenarios - -### Development Workflow Integration ```bash -# Pre-commit hook validation -skill_validator.py path/to/skill --tier POWERFUL --json +# 1. Validate structure (exit non-zero on failure — usable as a gate) +python3 engineering/skills/skill-tester/scripts/skill_validator.py engineering/skills/self-eval --json -# Comprehensive skill testing -script_tester.py path/to/skill --timeout 30 --sample-data +# 2. Test the skill's Python scripts (30s default timeout per script) +python3 engineering/skills/skill-tester/scripts/script_tester.py engineering/skills/self-eval --json -# Quality assessment and scoring -quality_scorer.py path/to/skill --detailed --recommendations +# 3. Score quality (fail CI below threshold with --minimum-score) +python3 engineering/skills/skill-tester/scripts/quality_scorer.py engineering/skills/self-eval --json --detailed --minimum-score 75 ``` -### CI/CD Pipeline Integration +Consume the JSON: validator emits `overall_score`, `compliance_level`, per-check `checks{}`; scorer emits `overall_score`, `letter_grade`, `tier_recommendation`, `dimensions`, and an `improvement_roadmap` — work the roadmap top-down, then re-run until the target score is met. + +For repo-wide auditing prefer `scripts/audit_skills.py` at the repo root (wraps the write-a-skill checklist runner across all skills). + +## What Each Tool Checks + +### skill_validator.py +- SKILL.md frontmatter parsing, required sections, minimum line counts per tier (`--tier BASIC|STANDARD|POWERFUL`) +- Required structure: SKILL.md, README.md, scripts/, references/, assets/, expected_outputs/ +- Python scripts: argparse present, stdlib-only imports + +### script_tester.py +- AST-based syntax validation; import analysis (flags external dependencies) +- Controlled execution with timeout protection (`--timeout`, default 30s) +- `--help` functionality verification; sample-data runs compared against expected_outputs/ + +### quality_scorer.py +Four dimensions, 25% each: **Documentation** (depth, examples, references), **Code Quality** (complexity, error handling, output consistency), **Completeness** (required dirs, sample data, expected outputs), **Usability** (help text, example clarity). Outputs 0-100 + A-F grade + tier recommendation. + +## Tier Classification + +| Tier | SKILL.md | Scripts | CLI surface | +|---|---|---|---| +| BASIC | ≥ 100 lines | 1 (100-300 LOC) | basic argparse | +| STANDARD | ≥ 200 lines | 1-2 (300-500 LOC) | subcommands, JSON + text output | +| POWERFUL | ≥ 300 lines | 2-3 (500-800 LOC) | multiple modes, CI integration | + +(Advisory for legacy skills; new skills follow write-a-skill — see scope note above.) + +## CI Integration + ```yaml -# GitHub Actions workflow example -- name: "validate-skill-quality" +# GitHub Actions: gate changed skills +- name: "validate-changed-skills" run: | - python skill_validator.py engineering/${{ matrix.skill }} --json | tee validation.json - python script_tester.py engineering/${{ matrix.skill }} | tee testing.json - python quality_scorer.py engineering/${{ matrix.skill }} --json | tee scoring.json + for skill in $changed_skills; do + python3 engineering/skills/skill-tester/scripts/skill_validator.py "$skill" --json + python3 engineering/skills/skill-tester/scripts/script_tester.py "$skill" + python3 engineering/skills/skill-tester/scripts/quality_scorer.py "$skill" --minimum-score 75 + done ``` -### Batch Repository Analysis -```bash -# Validate all skills in repository -find engineering/ -type d -maxdepth 1 | xargs -I {} skill_validator.py {} +Pre-commit hook: run the validator on the staged skill directory and block the commit on non-zero exit. -# Generate repository quality report -quality_scorer.py engineering/ --batch --output-format json > repo_quality.json -``` +## Verification Loop -## Output Formats & Reporting +A skill "passes" when, in one run from repo root: -### Dual Output Support -All tools provide both human-readable and machine-parseable output: +1. `skill_validator.py --json` exits 0, +2. `script_tester.py ` reports all scripts passing, and +3. `quality_scorer.py --minimum-score ` exits 0. -#### Human-Readable Format -``` -=== SKILL VALIDATION REPORT === -Skill: engineering/example-skill -Tier: STANDARD -Overall Score: 85/100 (B) +If any step fails, apply the top `improvement_roadmap` item and re-run all three — never report a partial pass. -Structure Validation: ✓ PASS -├─ SKILL.md: ✓ EXISTS (247 lines) -├─ README.md: ✓ EXISTS -├─ scripts/: ✓ EXISTS (2 files) -└─ references/: ⚠ MISSING (recommended) +## Troubleshooting -Documentation Quality: 22/25 (88%) -Code Quality: 20/25 (80%) -Completeness: 18/25 (72%) -Usability: 21/25 (84%) +- **Timeout errors** → raise `--timeout` or optimize the script under test +- **Import failures** → external deps detected; stdlib-only is the repo policy +- **Tier misclassification** → check line counts/LOC against the tier table; remember the write-a-skill exception for new skills -Recommendations: -• Add references/ directory with documentation -• Improve error handling in main.py -• Include more comprehensive examples -``` - -#### JSON Format -```json -{ - "skill_path": "engineering/example-skill", - "timestamp": "2026-02-16T16:41:00Z", - "validation_results": { - "structure_compliance": { - "score": 0.95, - "checks": { - "skill_md_exists": true, - "readme_exists": true, - "scripts_directory": true, - "references_directory": false - } - }, - "overall_score": 85, - "letter_grade": "B", - "tier_recommendation": "STANDARD", - "improvement_suggestions": [ - "Add references/ directory", - "Improve error handling", - "Include comprehensive examples" - ] - } -} -``` - -## Quality Assurance Standards - -### Code Quality Requirements -- **Standard Library Only**: No external dependencies (pip packages) -- **Error Handling**: Comprehensive exception handling with meaningful error messages -- **Output Consistency**: Standardized JSON schema and human-readable formatting -- **Performance**: Efficient validation algorithms with reasonable execution time -- **Maintainability**: Clear code structure, comprehensive docstrings, type hints where appropriate - -### Testing Standards -- **Self-Testing**: The skill-tester validates itself (meta-validation) -- **Sample Data Coverage**: Comprehensive test cases covering edge cases and error conditions -- **Expected Output Verification**: All sample runs produce verifiable, reproducible outputs -- **Timeout Protection**: Safe execution of potentially problematic scripts with timeout limits - -### Documentation Standards -- **Comprehensive Coverage**: All functions, classes, and modules documented -- **Usage Examples**: Clear, practical examples for all use cases -- **Integration Guides**: Step-by-step CI/CD and workflow integration instructions -- **Reference Materials**: Complete specification documents for standards and requirements - -## Integration Examples - -### Pre-Commit Hook Setup -```bash -#!/bin/bash -# .git/hooks/pre-commit -echo "Running skill validation..." -python engineering/skills/skill-tester/scripts/skill_validator.py engineering/new-skill --tier STANDARD -if [ $? -ne 0 ]; then - echo "Skill validation failed. Commit blocked." - exit 1 -fi -echo "Validation passed. Proceeding with commit." -``` - -### GitHub Actions Workflow -```yaml -name: "skill-quality-gate" -on: - pull_request: - paths: ['engineering/**'] - -jobs: - validate-skills: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - name: "setup-python" - uses: actions/setup-python@v4 - with: - python-version: '3.11' - - name: "validate-changed-skills" - run: | - changed_skills=$(git diff --name-only ${{ github.event.before }} | grep -E '^engineering/[^/]+/' | cut -d'/' -f1-2 | sort -u) - for skill in $changed_skills; do - echo "Validating $skill..." - python engineering/skills/skill-tester/scripts/skill_validator.py $skill --json - python engineering/skills/skill-tester/scripts/script_tester.py $skill - python engineering/skills/skill-tester/scripts/quality_scorer.py $skill --minimum-score 75 - done -``` - -### Continuous Quality Monitoring -```bash -#!/bin/bash -# Daily quality report generation -echo "Generating daily skill quality report..." -timestamp=$(date +"%Y-%m-%d") -python engineering/skills/skill-tester/scripts/quality_scorer.py engineering/ \ - --batch --json > "reports/quality_report_${timestamp}.json" - -echo "Quality trends: most recent daily reports for comparison..." -ls -1t reports/quality_report_*.json | head -30 -``` - -## Performance & Scalability - -### Execution Performance -- **Fast Validation**: Structure validation completes in <1 second per skill -- **Efficient Testing**: Script testing with timeout protection (configurable, default 30s) -- **Batch Processing**: Optimized for repository-wide analysis with parallel processing support -- **Memory Efficiency**: Minimal memory footprint for large-scale repository analysis - -### Scalability Considerations -- **Repository Size**: Designed to handle repositories with 100+ skills -- **Concurrent Execution**: Thread-safe implementation supports parallel validation -- **Resource Management**: Automatic cleanup of temporary files and subprocess resources -- **Configuration Flexibility**: Configurable timeouts, memory limits, and validation strictness - -## Security & Safety - -### Safe Execution Environment -- **Sandboxed Testing**: Scripts execute in controlled environment with timeout protection -- **Resource Limits**: Memory and CPU usage monitoring to prevent resource exhaustion -- **Input Validation**: All inputs sanitized and validated before processing -- **No Network Access**: Offline operation ensures no external dependencies or network calls - -### Security Best Practices -- **No Code Injection**: Static analysis only, no dynamic code generation -- **Path Traversal Protection**: Secure file system access with path validation -- **Minimal Privileges**: Operates with minimal required file system permissions -- **Audit Logging**: Comprehensive logging for security monitoring and troubleshooting - -## Troubleshooting & Support - -### Common Issues & Solutions - -#### Validation Failures -- **Missing Files**: Check directory structure against tier requirements -- **Import Errors**: Ensure only standard library imports are used -- **Documentation Issues**: Verify SKILL.md frontmatter and section completeness - -#### Script Testing Problems -- **Timeout Errors**: Increase timeout limit or optimize script performance -- **Execution Failures**: Check script syntax and import statement validity -- **Output Format Issues**: Ensure proper JSON formatting and dual output support - -#### Quality Scoring Discrepancies -- **Low Scores**: Review scoring rubric and improvement recommendations -- **Tier Misclassification**: Verify skill complexity against tier requirements -- **Inconsistent Results**: Check for recent changes in quality standards or scoring weights - -### Debugging Support -- **Verbose Mode**: Detailed logging and execution tracing available -- **Dry Run Mode**: Validation without execution for debugging purposes -- **Debug Output**: Comprehensive error reporting with file locations and suggestions - -## Future Enhancements - -### Planned Features -- **Machine Learning Quality Prediction**: AI-powered quality assessment using historical data -- **Performance Benchmarking**: Execution time and resource usage tracking across skills -- **Dependency Analysis**: Automated detection and validation of skill interdependencies -- **Quality Trend Analysis**: Historical quality tracking and regression detection - -### Integration Roadmap -- **IDE Plugins**: Real-time validation in popular development environments -- **Web Dashboard**: Centralized quality monitoring and reporting interface -- **API Endpoints**: RESTful API for external integration and automation -- **Notification Systems**: Automated alerts for quality degradation or validation failures - -## Conclusion - -The Skill Tester represents a critical infrastructure component for maintaining the high-quality standards of the claude-skills ecosystem. By providing comprehensive validation, testing, and scoring capabilities, it ensures that all skills meet or exceed the rigorous requirements for their respective tiers. - -This meta-skill not only serves as a quality gate but also as a development tool that guides skill authors toward best practices and helps maintain consistency across the entire repository. Through its integration capabilities and comprehensive reporting, it enables both manual and automated quality assurance workflows that scale with the growing claude-skills ecosystem. - -The combination of structural validation, runtime testing, and multi-dimensional quality scoring provides unparalleled visibility into skill quality while maintaining the flexibility needed for diverse skill types and complexity levels. As the claude-skills repository continues to grow, the Skill Tester will remain the cornerstone of quality assurance and ecosystem integrity. \ No newline at end of file +References: `references/` holds the structure specification, tier requirements matrix, and scoring rubric the tools implement. diff --git a/engineering/skills/tech-debt-tracker/SKILL.md b/engineering/skills/tech-debt-tracker/SKILL.md index 2253031d..19c86bbc 100644 --- a/engineering/skills/tech-debt-tracker/SKILL.md +++ b/engineering/skills/tech-debt-tracker/SKILL.md @@ -25,48 +25,42 @@ This skill offers three interconnected tools that form a complete tech debt mana Together, these tools enable engineering teams to make data-driven decisions about tech debt, balancing new feature development with maintenance work. +## Quick Start — scan → prioritize → dashboard + +All paths relative to this skill folder. The scanner's JSON output feeds the prioritizer directly; dated inventory snapshots feed the dashboard. + +### 1. Scan the codebase + +```bash +python3 scripts/debt_scanner.py /path/to/codebase --format json --output debt_inventory.json +``` + +Emits `debt_inventory.json` with `scan_metadata`, `summary`, `debt_items[]`, `file_statistics`, and `recommendations`. Report the `summary` counts to the user. (Dry run: `assets/sample_codebase`.) + +### 2. Prioritize the backlog + +```bash +python3 scripts/debt_prioritizer.py debt_inventory.json --framework wsjf --team-size 6 --sprint-capacity 20 --format json --output debt_priorities.json +``` + +Frameworks: `cost_of_delay` (default), `wsjf`, `rice`. Output contains `prioritized_backlog` (work top-down), `sprint_allocation` (paste into sprint planning), and `insights`. + +### 3. Track trends over time + +Keep dated snapshots (`debt_YYYY-MM-DD.json`), then: + +```bash +python3 scripts/debt_dashboard.py --input-dir snapshots/ --period monthly --format both --output debt_dashboard +``` + +Or pass files explicitly (samples: `assets/historical_debt_2024-01-15.json assets/historical_debt_2024-02-01.json`). The dashboard reports trend direction and executive-ready summaries — use it to verify a cleanup sprint actually reduced debt. + +### Verification loop + +After a remediation sprint: re-run step 1, re-run step 3 with the new snapshot, and assert the targeted categories' counts dropped. A cleanup that doesn't move the dashboard is rework, not debt paydown. + ## Technical Debt Classification Framework -→ See references/debt-frameworks.md for details - -## Implementation Roadmap - -### Phase 1: Foundation (Weeks 1-2) -1. Set up debt scanning infrastructure -2. Establish debt taxonomy and scoring criteria -3. Scan initial codebase and create baseline inventory -4. Train team on debt identification and reporting - -### Phase 2: Process Integration (Weeks 3-4) -1. Integrate debt tracking into sprint planning -2. Establish debt budgets and allocation rules -3. Create stakeholder reporting templates -4. Set up automated debt scanning in CI/CD - -### Phase 3: Optimization (Weeks 5-6) -1. Refine scoring algorithms based on team feedback -2. Implement trend analysis and predictive metrics -3. Create specialized debt reduction initiatives -4. Establish cross-team debt coordination processes - -### Phase 4: Maturity (Ongoing) -1. Continuous improvement of detection algorithms -2. Advanced analytics and prediction models -3. Integration with planning and project management tools -4. Organization-wide debt management best practices - -## Success Criteria - -**Quantitative Metrics:** -- 25% reduction in debt interest rate within 6 months -- 15% improvement in development velocity -- 30% reduction in production defects -- 20% faster code review cycles - -**Qualitative Metrics:** -- Improved developer satisfaction scores -- Reduced context switching during feature development -- Faster onboarding for new team members -- Better predictability in feature delivery timelines +→ See references/debt-frameworks.md for details (also: references/debt-classification-taxonomy.md, references/prioritization-framework.md, references/stakeholder-communication-templates.md) ## Common Pitfalls and How to Avoid Them diff --git a/engineering/universal-scraping-architect/SKILL.md b/engineering/universal-scraping-architect/SKILL.md index 7af8a00b..35294d59 100644 --- a/engineering/universal-scraping-architect/SKILL.md +++ b/engineering/universal-scraping-architect/SKILL.md @@ -5,9 +5,15 @@ description: "Use for web scraping, crawling, document extraction, API parsing, # Universal Scraping Architect -You are an expert web scraping and data extraction engineer. Your goal is to design complete, robust data pipelines with intelligent routing, validation, and token budget tracking—not brittle one-off scripts. +Design complete, robust data-extraction pipelines with intelligent routing, validation, and token-budget tracking — not brittle one-off scripts. -**Dependency Notice:** This skill utilizes `firecrawl`, `pandas`, `requests`, and `beautifulsoup4`. It uses a BYOK (Bring Your Own Key) pattern for Firecrawl. API keys must only be loaded via environment variables. +**Dependency Notice:** BYOK (Bring Your Own Key) pattern for Firecrawl; API keys must only be loaded via environment variables. Per-script dependencies: + +| Script | Dependencies | Exact CLI | +|---|---|---| +| `scripts/validate_extraction.py` | stdlib only | `python3 scripts/validate_extraction.py output.json --json` | +| `scripts/firecrawl_example.py` | `firecrawl`, `requests` (template; `--sample` runs offline) | `python3 scripts/firecrawl_example.py --sample` | +| `scripts/local_bs4_example.py` | `beautifulsoup4`, `pandas` (template; `--sample` runs offline) | `python3 scripts/local_bs4_example.py --sample` | ## Before Starting **Check for context first:** @@ -29,8 +35,8 @@ Use when Firecrawl handles URL discovery/web extraction, but local Python (Panda When executing a scraping task, always follow this sequence: 1. **Route the Approach:** Explicitly state whether Firecrawl or Local Python is being used and why. 2. **Track Budgets:** Estimate Firecrawl API quotas or LLM token context limits before executing large jobs. -3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. -4. **Validate & Clean:** Enforce required fields, catch empty outputs, flag duplicates, and normalize field names. +3. **Extract Safely:** Implement checkpointing for multi-page jobs. Handle pagination and dynamic layouts gracefully. Start from the editable runner templates — `scripts/firecrawl_example.py` (Mode 1) or `scripts/local_bs4_example.py` (Mode 2); run each with `--sample` first to see the expected summary shape without network access. +4. **Validate & Clean:** Run `python3 scripts/validate_extraction.py extracted_output.json --json` on every extraction result before delivering it. It exits 0 only on `{"status": "ok"}`; `warning` (empty output) or `error` (malformed JSON) exit 1 — fix and re-extract, never ship unvalidated data. Beyond this structural gate, also check required fields and duplicates against the pipeline spec before delivering. 5. **Format:** Default to CSV for tabular data, JSON for nested structures, and Markdown for clean text. ## Proactive Triggers diff --git a/finance/.claude-plugin/plugin.json b/finance/.claude-plugin/plugin.json index 3b3f853a..88343be5 100644 --- a/finance/.claude-plugin/plugin.json +++ b/finance/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "finance-skills", - "description": "3 finance skills: financial analyst (ratio analysis, DCF valuation, budgeting, forecasting), SaaS metrics coach (ARR, MRR, churn, CAC, LTV, NRR, Quick Ratio, 12-month projections), and business investment advisor. 7 Python automation tools. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "2 finance skills plus a router: financial analyst (ratio analysis, DCF valuation, budgeting, forecasting) and SaaS metrics coach (ARR, MRR, churn, CAC, LTV, NRR, Quick Ratio, 12-month projections). 7 Python automation tools. The business-investment-advisor skill ships as a separate nested plugin. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -12,4 +12,4 @@ "skills": [ "./skills" ] -} +} \ No newline at end of file diff --git a/finance/skills/finance-skills/SKILL.md b/finance/skills/finance-skills/SKILL.md index e4438500..95a3bdee 100644 --- a/finance/skills/finance-skills/SKILL.md +++ b/finance/skills/finance-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "finance-skills" -description: "Financial analyst agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Ratio analysis, DCF valuation, budget variance, rolling forecasts. 4 Python tools (stdlib-only)." +description: "Router/index for the 2 finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts) and saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -16,40 +16,36 @@ agents: - openclaw --- -# Finance Skills +# Finance Skills — Router -Production-ready financial analysis skill for strategic decision-making. +This plugin bundles **2 finance skills** (this router is the 3rd folder under `finance/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read finance/skills/financial-analyst/SKILL.md -``` +| Request signals | Skill | Path | +|---|---|---| +| Ratio analysis, DCF valuation, budget variance, driver-based forecasts | financial-analyst | `skills/financial-analyst/` | +| ARR/MRR, churn, CAC/LTV, NRR, quick ratio, SaaS benchmarks | saas-metrics-coach | `skills/saas-metrics-coach/` | -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/finance -``` +If both match (e.g., "value my SaaS company"), ask whether the user wants statement-level analysis (financial-analyst) or SaaS operating metrics (saas-metrics-coach). -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Financial Analyst | `financial-analyst/` | Ratio analysis, DCF, budget variance, forecasting | - -## Python Tools - -4 scripts, all stdlib-only: +## Quick start ```bash +# Example: route a statement-analysis request +cat finance/skills/financial-analyst/SKILL.md python3 finance/skills/financial-analyst/scripts/ratio_calculator.py --help -python3 finance/skills/financial-analyst/scripts/dcf_valuation.py --help -python3 finance/skills/financial-analyst/scripts/budget_variance_analyzer.py --help -python3 finance/skills/financial-analyst/scripts/forecast_builder.py --help + +# Or a SaaS metrics request +python3 finance/skills/saas-metrics-coach/scripts/metrics_calculator.py --help ``` +## Related (packaged separately, not in this bundle) + +- `finance/business-investment-advisor/` — investment thesis evaluation, ROI modeling (prompt-only skill, separate nested plugin) +- Root commands `/financial-health` and `/saas-health` wrap these skills' scripts. + ## Rules -- Load only the specific skill SKILL.md you need -- Always validate financial outputs against source data +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- Always validate financial outputs against the user's source data; outputs are analysis support, not investment advice. diff --git a/marketing-skill/.claude-plugin/plugin.json b/marketing-skill/.claude-plugin/plugin.json index f8c4a780..51af5434 100644 --- a/marketing-skill/.claude-plugin/plugin.json +++ b/marketing-skill/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "marketing-skills", - "description": "45 production-ready marketing skills across 8 pods: Content (copywriting, content strategy, content production), SEO + AEO (traditional audits, schema markup, programmatic SEO, site architecture, plus Answer Engine Optimization for LLM citation in ChatGPT/Perplexity/Claude/Gemini/Mistral), CRO (A/B testing, forms, popups, signup flows, pricing, onboarding), Channels (email sequences, social media, paid ads, cold email, X/Twitter growth), Growth (launch strategy, referral programs, free tools), Intelligence (competitor analysis, marketing psychology, analytics tracking), and Sales enablement. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", + "description": "44 production-ready marketing skills across 8 pods: Content (copywriting, content strategy, content production), SEO + AEO (traditional audits, schema markup, programmatic SEO, site architecture, plus Answer Engine Optimization for LLM citation in ChatGPT/Perplexity/Claude/Gemini/Mistral), CRO (A/B testing, forms, popups, signup flows, pricing, onboarding), Channels (email sequences, social media, paid ads, cold email, X/Twitter growth), Growth (launch strategy, referral programs, free tools), Intelligence (competitor analysis, marketing psychology, analytics tracking), and Sales enablement. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", diff --git a/marketing-skill/.codex/instructions.md b/marketing-skill/.codex/instructions.md index c3d1b87f..f3a5e575 100644 --- a/marketing-skill/.codex/instructions.md +++ b/marketing-skill/.codex/instructions.md @@ -10,7 +10,7 @@ When working on marketing tasks, use the marketing skill system: ## Context -If `marketing-context.md` exists in the project root, read it before any marketing task. It contains brand voice, audience personas, and competitive landscape. +If `.claude/product-marketing-context.md` exists, read it before any marketing task. It contains brand voice, audience personas, and competitive landscape. ## Python Tools @@ -29,7 +29,7 @@ python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py | Write content | content-production | | Plan content | content-strategy | | SEO audit | seo-audit | -| AI search optimization | ai-seo | +| AI search optimization / AEO | aeo | | Page conversion | page-cro | | Email sequences | email-sequence | | Pricing | pricing-strategy | @@ -37,6 +37,6 @@ python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py ## Rules -- Never load all 42 skills at once — route to 1-2 per request -- Check marketing-context.md before starting +- Never load all 44 skills at once — route to 1-2 per request +- Check `.claude/product-marketing-context.md` before starting - Use Python tools for scoring and validation, not manual judgment diff --git a/marketing-skill/CLAUDE.md b/marketing-skill/CLAUDE.md index e71ba8d4..b6db0896 100644 --- a/marketing-skill/CLAUDE.md +++ b/marketing-skill/CLAUDE.md @@ -2,12 +2,12 @@ ## For All Agents (Claude Code, Codex CLI, OpenClaw) -This directory contains 45 marketing skills organized into 8 specialist pods (Content, SEO + AEO, CRO, Channels, Growth, Intelligence, Sales enablement, Marketing ops). +This directory contains 44 marketing skills organized into 8 specialist pods (Content, SEO + AEO, CRO, Channels, Growth, Intelligence, Sales enablement, Marketing ops). ### How to Use 1. **Start with routing:** Read `marketing-ops/SKILL.md` — it has a routing matrix that maps user requests to the right skill. -2. **Check context:** If `marketing-context.md` exists, read it first. It has brand voice, personas, and competitive landscape. +2. **Check context:** If `.claude/product-marketing-context.md` exists, read it first. It has brand voice, personas, and competitive landscape. 3. **Load ONE skill:** Read only the specialist SKILL.md you need. Never bulk-load. ### Skill Map @@ -16,7 +16,6 @@ This directory contains 45 marketing skills organized into 8 specialist pods (Co - `marketing-ops/` — Router (read this to know where to go) - `content-production/` — Write content (blog posts, articles, guides) - `content-strategy/` — Plan what content to create -- `ai-seo/` — Optimize for AI search engines (ChatGPT, Perplexity, Google AI) - `aeo/` — Answer Engine Optimization (E-E-A-T scoring, schema injection, citation tracking across LLMs) - `seo-audit/` — Traditional SEO audit - `page-cro/` — Conversion rate optimization @@ -26,7 +25,7 @@ This directory contains 45 marketing skills organized into 8 specialist pods (Co ### Python Tools -58 scripts, all stdlib-only. Run directly: +59 scripts, all stdlib-only. Run directly: ```bash python3 /scripts/.py [args] ``` @@ -34,7 +33,7 @@ No pip install needed. Scripts include embedded samples for demo mode (run with ### Anti-Patterns -❌ Don't read all 45 SKILL.md files -❌ Don't skip marketing-context.md if it exists +❌ Don't read all 44 SKILL.md files +❌ Don't skip `.claude/product-marketing-context.md` if it exists ❌ Don't use content-creator (deprecated → use content-production) ❌ Don't install pip packages for Python tools diff --git a/marketing-skill/README.md b/marketing-skill/README.md index b4e0595a..798dc747 100644 --- a/marketing-skill/README.md +++ b/marketing-skill/README.md @@ -90,7 +90,7 @@ This marketing skills collection provides comprehensive marketing capabilities f ## 📦 Skills Catalog ### 1. Content Creator -**Package:** `content-creator.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/content-production/` | **Status:** ⚠️ Deprecated as standalone — use content-production | **Version:** 1.0 **Purpose:** Transform content creation with professional-grade brand voice analysis, SEO optimization, and platform-specific best practices. @@ -132,7 +132,7 @@ This marketing skills collection provides comprehensive marketing capabilities f --- ### 2. Marketing Demand & Acquisition -**Package:** `marketing-demand-acquisition.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/marketing-demand-acquisition/` | **Status:** ✅ Production Ready | **Version:** 1.1 **Purpose:** Expert demand generation, paid media, SEO, and partnerships for Series A+ startups scaling internationally. @@ -185,7 +185,7 @@ This marketing skills collection provides comprehensive marketing capabilities f --- ### 3. Marketing Strategy & Product Marketing -**Package:** `marketing-strategy-pmm.zip` | **Status:** ✅ Production Ready | **Version:** 1.0 +**Folder:** `skills/marketing-strategy-pmm/` | **Status:** ✅ Production Ready | **Version:** 1.0 **Purpose:** Product marketing, positioning, GTM strategy, and competitive intelligence for product launches and market expansion. diff --git a/marketing-skill/marketing_skills_roadmap.md b/marketing-skill/marketing_skills_roadmap.md index 8f7674b5..573579a4 100644 --- a/marketing-skill/marketing_skills_roadmap.md +++ b/marketing-skill/marketing_skills_roadmap.md @@ -12,9 +12,9 @@ The **content-creator** skill is ready for deployment and includes: - **Content Calendar Template**: Monthly planning and tracking system ### How to Deploy -1. Download the `content-creator.zip` file -2. Extract to your team's shared drive or tool repository -3. Install Python dependencies: `pip install pyyaml` +1. Copy the `skills/content-production/` folder (content-creator is deprecated; content-production supersedes it) +2. Place it in your team's shared drive or tool repository +3. No pip installs needed — scripts are stdlib-only 4. Team members can use with Claude by uploading the skill 5. Run training session on brand voice establishment diff --git a/marketing-skill/skills/ab-test-setup/SKILL.md b/marketing-skill/skills/ab-test-setup/SKILL.md index 7fd11737..ef1a05fa 100644 --- a/marketing-skill/skills/ab-test-setup/SKILL.md +++ b/marketing-skill/skills/ab-test-setup/SKILL.md @@ -82,16 +82,30 @@ We'll know this is true when [metrics]. ## Sample Size +### Calculate It (bundled tool) + +Use this skill's own calculator — don't eyeball it: + +```bash +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 # human-readable +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --json # for pipelines +python3 scripts/sample_size_calculator.py --baseline 0.05 --mde 0.20 --daily-traffic 2000 # adds test-duration estimate +``` + +Paste `sample_size_per_variation` and the duration estimate directly into the test plan's "Sample size + duration" row before any test is approved to run. + ### Quick Reference +Generated by `sample_size_calculator.py` (two-proportion z-test, α=0.05 two-tailed, 80% power; relative MDE): + | Baseline | 10% Lift | 20% Lift | 50% Lift | |----------|----------|----------|----------| -| 1% | 150k/variant | 39k/variant | 6k/variant | -| 3% | 47k/variant | 12k/variant | 2k/variant | -| 5% | 27k/variant | 7k/variant | 1.2k/variant | -| 10% | 12k/variant | 3k/variant | 550/variant | +| 1% | 163k/variant | 43k/variant | 7.7k/variant | +| 3% | 53k/variant | 14k/variant | 2.5k/variant | +| 5% | 31k/variant | 8.2k/variant | 1.5k/variant | +| 10% | 15k/variant | 3.8k/variant | 683/variant | -**Calculators:** +**Cross-check calculators** (should agree with the script within rounding): - [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) - [Optimizely's](https://www.optimizely.com/sample-size-calculator/) diff --git a/marketing-skill/skills/ad-creative/SKILL.md b/marketing-skill/skills/ad-creative/SKILL.md index 35c672ac..fb4f8eff 100644 --- a/marketing-skill/skills/ad-creative/SKILL.md +++ b/marketing-skill/skills/ad-creative/SKILL.md @@ -16,7 +16,7 @@ You are a performance creative director who has written thousands of ads. You kn ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): @@ -80,7 +80,7 @@ You have a winning creative. Now multiply it for testing or for multiple audienc |----------|--------|---------------|-----------------|-------| | Google RSA | Search | 30 chars (×15) | 90 chars (×4 descriptions) | Max 3 pinned | | Google Display | Display | 30 chars (×5) | 90 chars (×5) | Also needs 5 images | -| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Image text <20% | +| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Minimal image text (best practice) | | LinkedIn | Sponsored Content | 70 chars headline | 150 chars intro text | No click-bait | | Twitter/X | Promoted | 70 chars | 280 chars total | No deceptive tactics | | TikTok | In-Feed | No overlay headline | 80–100 chars caption | Hook in first 3s | diff --git a/marketing-skill/skills/ad-creative/references/platform-specs.md b/marketing-skill/skills/ad-creative/references/platform-specs.md index e86ff0e6..d66a03cb 100644 --- a/marketing-skill/skills/ad-creative/references/platform-specs.md +++ b/marketing-skill/skills/ad-creative/references/platform-specs.md @@ -50,7 +50,7 @@ Full specifications for each major ad platform. Use this when generating or vali | Description | 30 chars | Optional, below headline | | Link description | 20 chars | URL preview | -**Image text rule:** Images with >20% text surface area get reduced distribution. Meta's tool at meta.com/ads/inspector/ checks this. Keep text minimal on images — put copy in the primary text field. +**Image text:** Meta's old ">20% text = reduced distribution" rule was retired in 2021 and is no longer enforced — but text-light images still tend to outperform text-heavy ones, so keep image text minimal as a best practice and put copy in the primary text field. ### Story / Reel Ads | Element | Limit | Notes | @@ -102,7 +102,7 @@ Full specifications for each major ad platform. Use this when generating or vali **LinkedIn-specific rules:** - No "Click here" as standalone CTA -- No images with more than 20% text +- Keep image text minimal — text-heavy creative underperforms in feed (best practice, not an enforced rejection rule) - No misleading job descriptions or recruitment bait - Avoid generic corporate language — LinkedIn users are saturated with it - B2B works better when you lead with a specific insight or stat, not a product pitch diff --git a/marketing-skill/skills/aeo/SKILL.md b/marketing-skill/skills/aeo/SKILL.md index 64e5b082..72912017 100644 --- a/marketing-skill/skills/aeo/SKILL.md +++ b/marketing-skill/skills/aeo/SKILL.md @@ -72,9 +72,21 @@ The tracker (`citation_tracker.py`) maintains a local ledger of citations: Stores in `~/.aeo-data/citations.json` (local, no telemetry). +## References + +- `references/aeo_eeat_canon.md` — E-E-A-T methodology, industry thresholds, anti-patterns +- `references/llm_citation_patterns.md` — per-LLM citation selection heuristics (Perplexity, ChatGPT, Claude, Gemini, Mistral) +- `references/aeo_vs_seo.md` — when to invest in AEO vs SEO vs both +- `references/bot_access_and_monitoring.md` — AI crawler robots.txt matrix (the prerequisite check: a blocked bot zeroes that platform), Google Search Console AI Overviews monitoring, manual testing protocols, citation-drop diagnostic (merged from the former `ai-seo` skill) +- `references/extractable_content_patterns.md` — 7 copy-ready block templates (definition, steps, table, FAQ, attributed stat, expert quote, summary box) that answer engines reliably extract (merged from the former `ai-seo` skill) + ## Workflow ``` +0. Pre-flight: bot access + Check robots.txt against the crawler matrix in references/bot_access_and_monitoring.md + → a blocked GPTBot/PerplexityBot/ClaudeBot/Google-Extended is the first fix, always + 1. Audit existing content $ python3 scripts/aeo_audit.py --url https://example.com/blog/post → markdown report with composite score + 4-dimension breakdown diff --git a/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md b/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md new file mode 100644 index 00000000..017c3f3f --- /dev/null +++ b/marketing-skill/skills/aeo/references/bot_access_and_monitoring.md @@ -0,0 +1,137 @@ +# Bot Access + AI Citation Monitoring + +This reference answers two operational decisions: **can AI crawlers reach your content at all**, and **how do you know when you're being cited (or losing citations)?** + +Bot access is the prerequisite for every other AEO investment — perfect E-E-A-T and schema mean nothing if the crawler is blocked. Monitoring closes the loop: AEO is non-deterministic, so you iterate on evidence, not assumptions. + +Folded in from the former `ai-seo` skill (merged into `aeo` 2026-06); landscape data last validated 2026-03 — verify platform behavior with manual testing before major decisions. + +--- + +## Part 1: Bot Access + +### The AI Crawler Matrix + +Check `yourdomain.com/robots.txt`. These bots must NOT be blocked for the corresponding platform to index or cite you: + +| Bot user-agent | Platform it feeds | Blocking it means | +|---|---|---| +| `GPTBot` | OpenAI / ChatGPT | No ChatGPT search citations | +| `PerplexityBot` | Perplexity | No Perplexity citations | +| `ClaudeBot` / `anthropic-ai` | Anthropic / Claude | No Claude browse citations | +| `Google-Extended` | Google AI Overviews + Gemini | No AI Overview / Gemini grounding | +| `Applebot-Extended` | Apple Intelligence | No Apple Intelligence answers | +| `cohere-ai` | Cohere | No Cohere-backed answers | +| (Bingbot) | ChatGPT search + Microsoft Copilot | Both use Bing's index — Bing indexing is a prerequisite | + +**robots.txt to allow all major AI bots:** + +``` +User-agent: GPTBot +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Google-Extended +Allow: / +``` + +Notes: + +- Blocking training crawl ≠ blocking citation — for most platforms they are the same crawl. Selective `Disallow:` rules trade training exposure against citation visibility; there is no confirmed way to get one without the other. +- **A blocked AI bot is the single highest-priority AEO finding.** It zeroes visibility on that platform and is a 5-minute fix. Flag it before anything else. +- JavaScript-only content is effectively invisible to most AI crawlers — content that requires JS execution to render may never be extracted. + +### Indexing prerequisites per platform + +| Platform | Index used | Prerequisite | +|---|---|---| +| Google AI Overviews | Google's own index | You must rank in traditional Google search first — AI Overviews strongly prefer top-10 pages | +| ChatGPT (search) | Bing API + internal | Submit sitemap to Bing Webmaster Tools; verify with URL Inspection | +| Perplexity | Own crawler + Brave + Bing | Allow PerplexityBot; real-time retrieval rewards fresh content | +| Claude (browse) | Brave + direct fetch | Allow ClaudeBot; clean fetchable HTML | +| Microsoft Copilot | Bing | Same Bing requirements as ChatGPT | + +### Cross-platform signal summary + +| Signal | AI Overviews | ChatGPT | Perplexity | Claude | Copilot | +|---|---|---|---|---|---| +| Must rank in traditional search | Yes | Bing only | No | No | Bing only | +| Schema markup impact | High | Medium | Low-Medium | Medium | Medium | +| Content recency weight | High | Medium | Very high | Medium | Medium | +| Original data advantage | High | High | High | High | High | +| Author attribution impact | Medium | High | Low | High | Medium | + +(For per-LLM citation selection heuristics, see `llm_citation_patterns.md` — this table covers only access/weighting signals.) + +--- + +## Part 2: Monitoring + +The honest truth: AI citation monitoring is immature. There is no Search Console equivalent for Perplexity or ChatGPT. The reliable stack today is **Google Search Console (for AI Overviews) + weekly manual testing + the `citation_tracker.py` ledger in this skill**. + +### Google Search Console — AI Overviews (best current tooling) + +1. Search Console → Performance → Search results +2. Filter: "Search type" → "AI Overviews" +3. Date range: last 90 days minimum + +What to act on: + +- Sort by impressions → your current AI Overview presences +- Impressions growing + clicks dropping on a query → an AI Overview is answering it; you're cited but not visited (AI Overview CTR typically runs 50-70% below organic) +- Sharp impression drops → you likely lost an AI Overview slot; run the drop diagnostic below + +Frequency: weekly check; monthly CSV export for trends. + +### Manual testing protocol (Perplexity, ChatGPT, Copilot) + +Weekly, for your top 10-20 target queries, in a fresh/incognito session: + +1. Run the query on each platform +2. Check the sources panel / citations +3. Record: cited (yes/no), position among sources, which URL, top cited competitor + +Log results with this skill's `citation_tracker.py` (local ledger at `~/.aeo-data/citations.json`). Interpretation: + +- Cited 4/4 weeks → stable (protect the page; don't restructure it) +- Cited 2/4 weeks → fragile (strengthen extractability + authority signals) +- Never cited → gap (page lacks extractable patterns — see `extractable_content_patterns.md`) + +ChatGPT citations vary by session — treat them as probabilistic and test monthly, not weekly; the goal is appearing in the citation set, not every time. + +### Indirect traffic signals + +- **Referrals**: filter GA4 for `perplexity.ai`, `chat.openai.com`, `claude.ai`, `copilot.microsoft.com` — low volume, high intent +- **Direct-traffic anomalies** to deep content pages (not homepage) can signal AI-driven attention (users copy/paste cited URLs) + +### When citations drop — diagnostic order + +1. **robots.txt** — did someone block an AI bot? (Most common, fastest fix; recovery typically 1-4 weeks after unblocking) +2. **Page structure** — was the definition block, FAQ, or steps section removed in an edit? +3. **Competitor** — did someone publish a more extractable page on the same query? +4. **Page health** — noindex added, canonical changed, Core Web Vitals regressed? +5. **Authority** — significant backlink loss; check for manual actions in Search Console + +| Root cause | Fix | +|---|---| +| AI bot blocked | Restore robots.txt allow rules | +| Patterns removed | Restore definition/FAQ/steps blocks | +| Competitor outranked | Add specifics, original data, schema | +| Authority drop | Rebuild links; check manual penalties | +| Content stale | Refresh data with current year | + +--- + +## Citations (6 sources) + +1. Google Search Central — "AI features and your website" + Search Console AI Overviews reporting documentation (developers.google.com/search) +2. OpenAI — GPTBot documentation (platform.openai.com/docs/gptbot) +3. Perplexity — PerplexityBot crawler documentation (docs.perplexity.ai) +4. Anthropic — "Does Anthropic crawl data from the web?" ClaudeBot support documentation (support.anthropic.com) +5. Bing Webmaster Tools documentation — indexing and URL inspection (bing.com/webmasters) +6. Kevin Indig — "Growth Memo" analyses of AI Overviews CTR impact and zero-click behavior (growth-memo.com) diff --git a/marketing-skill/skills/aeo/references/extractable_content_patterns.md b/marketing-skill/skills/aeo/references/extractable_content_patterns.md new file mode 100644 index 00000000..8d30340a --- /dev/null +++ b/marketing-skill/skills/aeo/references/extractable_content_patterns.md @@ -0,0 +1,287 @@ +# Extractable Content Patterns for AI Citability + +Ready-to-use block templates for the content patterns answer engines reliably extract and cite. Folded in from the former `ai-seo` skill (merged into `aeo` 2026-06). Use these when `aeo_audit.py` flags low structure scores, and apply them via `aeo_optimizer.py` rewrite modes. + +--- + +## Why Patterns Matter + +AI systems don't read pages the way humans do. They scan for extractable chunks — self-contained passages that can be pulled out and quoted without losing meaning. + +The patterns below are structured to be self-contained by design. If the AI pulls paragraph 3 without paragraph 2, the citation should still make sense. + +--- + +## Pattern 1: Definition Block + +**Used for:** "What is X" queries — the most common AI Overview trigger. + +**Requirements:** +- First sentence: direct definition +- Second sentence: why it matters or how it works +- Third sentence (optional): example or context +- Placed in first 300 words of the page + +**Template:** +```markdown +**[Term]** is [precise definition — what it is, what it does, who uses it]. +[One sentence on why it matters or what problem it solves]. +[Optional: one sentence example — "For example, a SaaS company might use X to..."]. +``` + +**Example:** +```markdown +**Churn rate** is the percentage of customers who cancel or stop using a service within a given period, typically measured monthly or annually. It directly impacts recurring revenue — a 5% monthly churn means losing over half your customer base each year. For subscription SaaS, a healthy monthly churn rate is typically below 2%. +``` + +**Tips:** +- Bold the term on its first use +- Don't start with "In the world of..." or "When it comes to..." +- The definition should work even if the reader knows nothing about the topic + +--- + +## Pattern 2: Numbered Steps (How-To) + +**Used for:** "How to X" and "How do I X" queries. + +**Requirements:** +- Numbered list (not bulleted) +- Each step starts with an action verb +- Each step is self-contained (can be cited alone) +- 5-10 steps maximum +- Pair with HowTo schema markup + +**Template:** +```markdown +## How to [Task] + +1. **[Verb phrase]** — [1-2 sentence explanation of this specific step] +2. **[Verb phrase]** — [1-2 sentence explanation] +3. **[Verb phrase]** — [1-2 sentence explanation] +4. **[Verb phrase]** — [1-2 sentence explanation] +5. **[Verb phrase]** — [1-2 sentence explanation] +``` + +**Example:** +```markdown +## How to Reduce SaaS Churn + +1. **Define your activation event** — Identify the specific action that signals a user has experienced core product value. For Slack, it's 2,000 messages sent. For Dropbox, it's saving the first file. +2. **Instrument the activation funnel** — Add event tracking from signup to activation. Find the step where most users drop off — that's your highest-leverage point. +3. **Build a customer health score** — Combine login frequency, feature adoption, and support ticket volume into a single score. Customers below 40 get proactive outreach. +4. **Segment churn by cohort** — Not all churn looks the same. Compare churn rates by acquisition channel, onboarding path, and company size to find patterns. +5. **Interview churned customers** — The customers who left quietly are more valuable than the ones who complained. Call 10 churned accounts per month and ask what they were trying to accomplish. +``` + +**Schema markup (JSON-LD):** +```json +{ + "@context": "https://schema.org", + "@type": "HowTo", + "name": "How to [Task]", + "step": [ + {"@type": "HowToStep", "name": "Step 1 name", "text": "Step 1 explanation"}, + {"@type": "HowToStep", "name": "Step 2 name", "text": "Step 2 explanation"} + ] +} +``` + +--- + +## Pattern 3: Comparison Table + +**Used for:** "X vs Y" and "best X for Y" queries. + +**Requirements:** +- Header row with category names +- First column: feature or criterion +- Remaining columns: the things being compared +- Keep it focused — 5-10 rows maximum +- Don't try to cover everything; cover what matters most + +**Template:** +```markdown +| Feature | [Option A] | [Option B] | [Option C] | +|---|---|---|---| +| [Criterion 1] | [Value] | [Value] | [Value] | +| [Criterion 2] | [Value] | [Value] | [Value] | +| [Criterion 3] | [Value] | [Value] | [Value] | +| Best for | [Audience A] | [Audience B] | [Audience C] | +| Pricing | [Range] | [Range] | [Range] | +``` + +**Tips:** +- Put the most important criteria first +- Use simple values — "Yes / No / Partial" beats long prose in cells +- Include a "Best for" row — AI systems use this for recommendation queries +- Add a sentence below the table summarizing the verdict: "X is best for teams that need A; Y is better when B matters more." + +--- + +## Pattern 4: FAQ Block + +**Used for:** Question-style queries, People Also Ask queries, voice search. + +**Requirements:** +- Question phrased exactly as someone would ask it (natural language) +- Answer is complete in 2-4 sentences (no "read more in section 3") +- 5-10 FAQs per block +- Pair with FAQPage schema markup + +**Template:** +```markdown +## Frequently Asked Questions + +**What is [X]?** +[2-4 sentence complete answer] + +**How does [X] work?** +[2-4 sentence complete answer] + +**What's the difference between [X] and [Y]?** +[2-4 sentence complete answer] + +**How much does [X] cost?** +[2-4 sentence complete answer] + +**Is [X] right for [audience]?** +[2-4 sentence complete answer] +``` + +**Schema markup (JSON-LD):** +```json +{ + "@context": "https://schema.org", + "@type": "FAQPage", + "mainEntity": [ + { + "@type": "Question", + "name": "What is [X]?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Complete answer text here" + } + } + ] +} +``` + +**Tips:** +- Write questions the way users actually type or speak them — use Google's "People Also Ask" as a source +- Answers should be complete without needing context from anywhere else on the page +- Don't start answers with "Great question" or "That's a common question" — just answer + +--- + +## Pattern 5: Statistic with Attribution + +**Used for:** Data queries, "how many" queries, research-backed claims. + +**Requirements:** +- Named source (not "a study" — the actual organization name) +- Year of the data +- Specific number (not "many" or "most") +- Context (what the number means) + +**Template:** +```markdown +According to [Organization Name]'s [Report Name] ([Year]), [specific statistic with units]. [One sentence on what this means or why it matters]. +``` + +**Example:** +```markdown +According to the Baymard Institute's 2024 UX benchmarking study, 69.8% of online shopping carts are abandoned before purchase. For a $1M/month ecommerce store, recovering just 5% of abandoned carts represents $35,000 in monthly revenue. +``` + +**Tips:** +- Link to the original source (AI systems and readers both benefit) +- If data is from your own research, say so: "In our 2025 survey of 500 SaaS founders..." +- Proprietary data is the highest-value citation target — AI systems actively seek original research + +--- + +## Pattern 6: Expert Quote Block + +**Used for:** Authority building, "what do experts say" queries. + +**Requirements:** +- Full name of the person quoted +- Their title and organization +- A quote that's substantive (not a generic endorsement) +- Brief context sentence before the quote + +**Template:** +```markdown +[Context sentence explaining why this person's view matters.] + +"[Direct quote — specific, substantive, something only they would say]," says [Full Name], [Title] at [Organization]. +``` + +**Example:** +```markdown +Patrick Campbell, founder of ProfitWell (acquired by Paddle), studied pricing data from over 30,000 SaaS companies before reaching a counterintuitive conclusion about churn. + +"Most churn that looks like pricing dissatisfaction is actually failed onboarding," says Campbell. "The customer never saw the value that justified the price. That's a different problem than being too expensive." +``` + +**Tips:** +- Don't use generic quotes ("innovation is key to success") — they add nothing +- Quotes should contain a specific claim, data point, or perspective +- If quoting your own team: "[Name], [Title] at [Company Name]" is still valid +- Live quotes (from interviews or primary research) outperform secondary quotes from other articles + +--- + +## Pattern 7: Quick-Scan Summary Box + +**Used for:** Queries where users want the TL;DR before committing to the full article. + +**Requirements:** +- Placed near the top of the article (after the intro) +- 3-7 key takeaways +- Each bullet stands alone — no context required +- Labeled clearly ("Key Takeaways" or "Quick Summary") + +**Template:** +```markdown +**Key Takeaways** +- [Specific, complete takeaway — could be read as a tweet] +- [Specific, complete takeaway] +- [Specific, complete takeaway] +- [Specific, complete takeaway] +- [Specific, complete takeaway] +``` + +**Tips:** +- This is often the block AI systems extract for "summary" type queries +- Make each bullet specific: "Monthly churn below 2% is considered healthy for most SaaS" beats "Churn should be low" +- Don't repeat the article intro verbatim — these should be the most actionable insights + +--- + +## Combining Patterns + +The most citable pages combine multiple patterns throughout the piece: + +**Recommended page structure for maximum AI extractability:** +1. Definition block (first 300 words) +2. Quick summary box (right after intro) +3. Body sections with numbered steps or subsections +4. Data points with full attribution throughout +5. Comparison table (if competitive topic) +6. FAQ block (before conclusion) +7. Expert quote (to add authority) + +A page with all 7 patterns has significantly more extractable surface area than a page with prose only. The AI has more options to pull from and a higher probability of finding something that perfectly matches the query. + +--- + +## Citations (6 sources) + +1. Google Search Central — Featured snippets and structured data guidelines (developers.google.com/search) +2. Schema.org — FAQPage and HowTo type definitions (schema.org) +3. Backlinko (Brian Dean) — "Definitive Guide to Featured Snippets" extraction-format research +4. Baymard Institute — UX benchmarking methodology cited in the statistic-attribution example (baymard.com) +5. Nielsen Norman Group — "How People Read Online" scanning research underpinning self-contained blocks (nngroup.com) +6. Aggarwal et al. — "GEO: Generative Engine Optimization" (KDD 2024), empirical evidence that citations, statistics, and quotations increase LLM source visibility diff --git a/marketing-skill/skills/analytics-tracking/SKILL.md b/marketing-skill/skills/analytics-tracking/SKILL.md index 2047e248..8841e92d 100644 --- a/marketing-skill/skills/analytics-tracking/SKILL.md +++ b/marketing-skill/skills/analytics-tracking/SKILL.md @@ -18,7 +18,7 @@ Bad tracking is worse than no tracking. Duplicate events, missing parameters, un ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: @@ -41,7 +41,17 @@ Gather this context: ## How This Skill Works ### Mode 1: Set Up From Scratch -No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure conversions. +No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure key events. + +Start from the generator, then customize: + +```bash +python3 scripts/tracking_plan_generator.py # embedded sample → full tracking plan +python3 scripts/tracking_plan_generator.py plan.json # your funnel definition +python3 scripts/tracking_plan_generator.py --json # parseable JSON for pipelines +``` + +Its output (event taxonomy + parameters + GA4/GTM config checklist) is the working draft for the Event Taxonomy Design section below — review every generated event name against the naming convention before implementing. ### Mode 2: Audit Existing Tracking Tracking exists but you don't trust the data, coverage is incomplete, or you're adding new goals. We'll audit what's there, gap-fill, and clean up. @@ -156,18 +166,18 @@ window.dataLayer.push({ }); ``` -### Conversions Configuration +### Key Events Configuration -Mark these events as conversions in GA4 → Admin → Conversions: +Mark these events as key events in GA4 → Admin → Key events (GA4 renamed "Conversions" to "Key events" in March 2024 — "conversions" now refers only to Google Ads conversion actions): - `signup_completed` - `checkout_completed` - `demo_requested` - `trial_started` (if separate from signup) **Rules:** -- Max 30 conversion events per property — curate, don't mark everything -- Conversions are retroactive in GA4 — turning one on applies to 6 months of history -- Don't mark micro-conversions as conversions unless you're optimizing ad campaigns for them +- Max 30 key events per property — curate, don't mark everything +- Key events are retroactive in GA4 — turning one on applies to 6 months of history +- Don't mark micro-conversions as key events unless you're also optimizing ad campaigns for them --- @@ -348,7 +358,7 @@ Surface these without being asked: | "Set up GTM" | Tag/trigger/variable configuration for each event, container setup checklist | | "Debug missing events" | Structured debugging steps using GTM Preview + GA4 DebugView + Network tab | | "Set up conversion tracking" | Conversion action configuration for GA4 + Google Ads + Meta | -| "Generate tracking plan" | Run `scripts/tracking_plan_generator.py` with your inputs | +| "Generate tracking plan" | Run `python3 scripts/tracking_plan_generator.py [plan.json] [--json]` — event taxonomy + GA4/GTM checklist | --- diff --git a/marketing-skill/skills/churn-prevention/SKILL.md b/marketing-skill/skills/churn-prevention/SKILL.md index 3b2622cd..4f7f687a 100644 --- a/marketing-skill/skills/churn-prevention/SKILL.md +++ b/marketing-skill/skills/churn-prevention/SKILL.md @@ -18,7 +18,7 @@ Churn is a revenue leak you can plug. A 20% save rate on voluntary churners and ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/cold-email/SKILL.md b/marketing-skill/skills/cold-email/SKILL.md index 51735f1a..ed6b3b73 100644 --- a/marketing-skill/skills/cold-email/SKILL.md +++ b/marketing-skill/skills/cold-email/SKILL.md @@ -16,7 +16,7 @@ You are an expert in B2B cold email outreach. Your goal is to help write, build, ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: @@ -242,15 +242,25 @@ Surface these without being asked: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/email_sequence_analyzer.py sequence.json` (no arg = embedded demo; `-` reads stdin) | Per-email 0-100 score across word count, reading level, personalization, CTA clarity, spam triggers, subject lines | + +Run it on every drafted sequence before delivering: any email scoring below 70 gets rewritten against the flagged dimensions (spam triggers and CTA clarity first), then re-scored. + +--- + ## Output Artifacts | When you ask for... | You get... | |---------------------|------------| | Write a cold email | First-touch email + 3 subject line variants + brief rationale for structure choices | -| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up | +| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up — scored with `email_sequence_analyzer.py` before delivery | | Critique my email | Line-by-line assessment + rewrite + explanation of each change | | Write follow-ups only | Follow-up emails 2-6 with unique angles per email + breakup email | -| Analyze sequence performance | Diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | +| Analyze sequence performance | `email_sequence_analyzer.py` score report + diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations | --- diff --git a/marketing-skill/skills/competitor-alternatives/SKILL.md b/marketing-skill/skills/competitor-alternatives/SKILL.md index 6490e557..1080d4f8 100644 --- a/marketing-skill/skills/competitor-alternatives/SKILL.md +++ b/marketing-skill/skills/competitor-alternatives/SKILL.md @@ -263,6 +263,16 @@ Proactively offer competitor page creation when: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Comparison matrix builder | `python3 scripts/comparison_matrix_builder.py --input competitors.json --markdown` (no input = embedded demo; `--json` for pipelines) | Feature-by-feature comparison matrix ready to paste into the vs-page comparison table | + +Feed it the Competitor Intelligence File data (features + pricing per competitor); its markdown output is the canonical comparison table for every Vs Page below — don't hand-build the table. + +--- + ## Output Artifacts | Artifact | Format | Description | diff --git a/marketing-skill/skills/content-humanizer/SKILL.md b/marketing-skill/skills/content-humanizer/SKILL.md index 2be46ee2..39347ae4 100644 --- a/marketing-skill/skills/content-humanizer/SKILL.md +++ b/marketing-skill/skills/content-humanizer/SKILL.md @@ -18,13 +18,13 @@ This is not a cleaning service. You're not just removing "delve" and calling it ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. +If `.claude/product-marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one. Gather what you need before starting: ### What you need - **The content** — paste the draft to humanize -- **Brand voice notes** — if no `marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." +- **Brand voice notes** — if no `.claude/product-marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love." - **Audience** — who reads this? (This changes what "human" sounds like) - **Goal** — what should this piece do? (Knowing the goal tells you how much personality is appropriate) @@ -51,7 +51,15 @@ Run all three in one pass when you have enough context. Split them when the clie Scan the content for these categories. Score severity: 🔴 critical (kills credibility) / 🟡 medium (softens impact) / 🟢 minor (polish only). -See [references/ai-tells-checklist.md](references/ai-tells-checklist.md) for the comprehensive detection list. +Start with the mechanical pass: + +```bash +python3 scripts/humanizer_scorer.py draft.md --json +``` + +It emits a 0-100 human-ness score. Interpretation: **80+** light polish only; **60-79** targeted pattern removal (Mode 2); **below 60** the AI fingerprint density is too high for a patch job — recommend a full rewrite, not an edit. Re-run after humanizing; the score must move. + +See [references/ai-tells-checklist.md](references/ai-tells-checklist.md) for the comprehensive detection list. Note: the tell vocabulary below is a snapshot — newer models have different tells, so check the checklist's "last validated" date and refresh it when auditing against current-generation output. ### The Core AI Tell Categories @@ -137,7 +145,7 @@ Every vague claim is an invitation to doubt. Replace: **Before:** "Many companies have seen significant improvements by implementing this strategy." -**After:** "HubSpot published their onboarding funnel data in 2023 — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." +**After:** "[Named company] published their onboarding funnel data in [year] — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error." (Name a real, current source with its year — the structure is what matters: named source + dated data + specific number.) If you don't have specific data, be honest: "I haven't seen controlled studies on this, but in my experience working with SaaS onboarding flows, the pattern is consistent: earlier activation = higher retention." @@ -170,7 +178,7 @@ Humanizing removes AI. Voice injection makes it *yours*. ### Read the Voice Blueprint First -If `marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. +If `.claude/product-marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it. **What to extract from a voice example:** - Sentence length preference (short punchy vs. longer flowing?) @@ -222,7 +230,7 @@ What changed: Flag these without being asked: - **AI fingerprint density too high** — If the piece has 10+ AI tells per 500 words, a patch job won't work. Flag that the piece needs a full rewrite, not an edit. Trying to polish a piece that's 80% AI patterns produces AI patterns with nicer words. -- **Voice context missing** — If `marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. +- **Voice context missing** — If `.claude/product-marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time. - **Specificity gap** — If the piece makes 5+ vague claims with zero data or attribution, flag it to the user. You can make the prose flow better, but you can't invent specific proof. They need to provide it. - **Tone mismatch after humanizing** — If the piece is now genuinely human but sounds like a different brand than everything else the client publishes, flag it. Consistency matters as much as quality. - **Over-editing risk** — If the original content has one or two genuinely good paragraphs buried in the AI mush, flag them before rewriting. Don't accidentally destroy the good parts. @@ -258,4 +266,4 @@ When auditing: name the pattern → explain why it reads as AI → give the spec - **content-production**: Use to produce the initial draft. Run content-humanizer after drafting, before the SEO optimization pass. - **copywriting**: Use for conversion copy — landing pages, CTAs, headlines. content-humanizer works on longer-form pieces; copywriting handles short punchy copy with different principles. - **content-strategy**: Use when deciding what content to create. NOT for voice or draft execution. -- **ai-seo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. +- **aeo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted. diff --git a/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md b/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md index 474095e6..32351313 100644 --- a/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md +++ b/marketing-skill/skills/content-humanizer/references/ai-tells-checklist.md @@ -2,6 +2,8 @@ A comprehensive reference for detecting AI-generated or AI-assisted writing patterns. Use this during Mode 1 (Detect) to audit content before editing. +**Last validated:** 2026-06 against then-current frontier models. AI-tell vocabularies age fast — the "delve"-era list below reflects 2023-2025 model output; newer models exhibit different tells. Re-validate this list every ~6 months against fresh model output and date the revision here. + Rate each finding: 🔴 Critical (rewrites required) / 🟡 Medium (edits needed) / 🟢 Minor (polish) --- diff --git a/marketing-skill/skills/content-production/SKILL.md b/marketing-skill/skills/content-production/SKILL.md index 858c9a09..5f81a556 100644 --- a/marketing-skill/skills/content-production/SKILL.md +++ b/marketing-skill/skills/content-production/SKILL.md @@ -18,7 +18,7 @@ This is the execution engine — not the strategy layer. You're here to build, n ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing. Gather this context (ask in one shot, don't drip): @@ -143,10 +143,18 @@ Don't pad the conclusion. If it's done, it's done. ## Mode 3: Optimize & Polish -Draft exists. Run this in order. +Draft exists. Run this in order. Each pass has a bundled tool — run the tool first, then do the manual checks on what it can't see. ### SEO Pass +Run the optimizer first: + +```bash +python3 scripts/seo_optimizer.py draft.md --keyword "primary keyword" --secondary "secondary,phrases" +``` + +Fix what it flags, then verify manually: + - **Title tag**: Contains primary keyword, under 60 characters, curiosity-driving - **H1**: Different from title tag, keyword-rich, reads naturally - **H2s**: At least 2-3 contain secondary keywords or related phrases @@ -156,7 +164,7 @@ Draft exists. Run this in order. ### Readability Pass -Run `scripts/content_scorer.py` on the draft. Target score: 70+. +Run `python3 scripts/content_scorer.py draft.md --json` on the draft (emits a 0-100 score). Target score: 70+. Manual checks: - Average sentence length: aim for 15-20 words, mix it up @@ -164,6 +172,16 @@ Manual checks: - No jargon without explanation (for non-expert audiences) - Active voice: find passive constructions and flip them +### Brand Voice Pass + +Check the draft against the brand's voice profile (from `.claude/product-marketing-context.md`): + +```bash +python3 scripts/brand_voice_analyzer.py draft.md --format json +``` + +It reports tone markers, sentence-rhythm stats, and vocabulary fingerprint. Compare against the brand's established profile; rewrite sections that drift (e.g., formal drift in a casual brand). + ### Structure Audit - Does the intro deliver on the headline's promise? @@ -187,7 +205,13 @@ Write: ### Quality Gates — Don't Publish Until These Pass -See [references/optimization-checklist.md](references/optimization-checklist.md) for the full pre-publish checklist. +Run the gate checker — it enforces the non-negotiables mechanically: + +```bash +python3 scripts/content_quality_gates.py draft.md --json +``` + +A failing gate blocks publish; fix and re-run until clean. See [references/optimization-checklist.md](references/optimization-checklist.md) for the full pre-publish checklist. Core gates: - [ ] Primary keyword appears naturally 3-5x (not stuffed) @@ -240,6 +264,6 @@ When reviewing drafts: flag issues → explain impact → give specific fix. Don - **content-strategy**: Use when deciding *what* to write — topics, calendar, pillar structure. NOT for writing the actual piece (that's this skill). - **content-humanizer**: Use after drafting when the piece sounds robotic or AI-generated. Run this before the optimization pass. -- **ai-seo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. +- **aeo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO. - **copywriting**: Use for landing pages, CTAs, and conversion copy. NOT for long-form content (that's this skill). - **seo-audit**: Use when auditing an existing content library for SEO gaps. NOT for single-piece production. diff --git a/marketing-skill/skills/content-production/references/optimization-checklist.md b/marketing-skill/skills/content-production/references/optimization-checklist.md index 01531893..7fa8d160 100644 --- a/marketing-skill/skills/content-production/references/optimization-checklist.md +++ b/marketing-skill/skills/content-production/references/optimization-checklist.md @@ -102,7 +102,7 @@ Run this before every piece goes live. Each section is a gate — fail a gate, f ## Gate 6: Brand & Voice -- [ ] Matches brand voice (check `marketing-context.md` if available) +- [ ] Matches brand voice (check `.claude/product-marketing-context.md` if available) - [ ] Consistent POV throughout (first person, second person, or third — pick one) - [ ] Consistent tense (present or past — don't mix) - [ ] No off-brand claims (anything that overpromises, contradicts other content, or sounds unlike us) diff --git a/marketing-skill/skills/content-strategy/SKILL.md b/marketing-skill/skills/content-strategy/SKILL.md index c3400c50..bda4a5b7 100644 --- a/marketing-skill/skills/content-strategy/SKILL.md +++ b/marketing-skill/skills/content-strategy/SKILL.md @@ -44,7 +44,26 @@ Gather this context (ask if not provided): --- ## Searchable vs Shareable -→ See references/content-strategy-reference.md for details + +The core classification decision for every topic: + +- **Searchable** — people already query this (keyword volume exists). Goal: rank and convert. Format: use-case pages, comparisons, how-tos, hub/spoke clusters. Judged by rankings + organic conversions over 6-12 months. +- **Shareable** — nobody searches it yet, but it spreads (original data, contrarian POV, strong narrative). Goal: reach + links + brand. Judged by distribution (shares, referral traffic, backlinks) in the first weeks. + +**Decision rule:** if the topic has meaningful search volume AND clear buyer intent → searchable (build it into a cluster). If it has no volume but a distribution hook → shareable (plan the launch channel before writing). If both → searchable structure with a shareable angle (best ROI). If neither → don't write it. + +Full treatment: references/content-strategy-reference.md + +## Topic Cluster Mapping (bundled tool) + +Once priority topics exist, group them mechanically: + +```bash +python3 scripts/topic_cluster_mapper.py --file keywords.txt # one topic/keyword per line +python3 scripts/topic_cluster_mapper.py --file keywords.txt --json # for pipelines +``` + +Its cluster output is the starting point for §3 Topic Cluster Map below — review cluster boundaries by intent (the tool groups lexically; you verify buyer-stage coherence). ## Output Format diff --git a/marketing-skill/skills/copy-editing/SKILL.md b/marketing-skill/skills/copy-editing/SKILL.md index 2e2f206c..4c754fb5 100644 --- a/marketing-skill/skills/copy-editing/SKILL.md +++ b/marketing-skill/skills/copy-editing/SKILL.md @@ -50,10 +50,11 @@ Edit copy through seven sequential passes, each focusing on one dimension. After - Burying the point in qualifications **Process:** -1. Read through quickly, highlighting unclear parts -2. Don't correct yet—just note problem areas -3. After marking issues, recommend specific edits -4. Verify edits maintain the original intent +1. Score the draft mechanically first: `python3 scripts/readability_scorer.py --file draft.md` (Flesch score, passive-voice %, filler-word count; add `--json` for pipelines). Anything it flags is your starting highlight list. +2. Read through quickly, highlighting unclear parts the scorer can't see +3. Don't correct yet—just note problem areas +4. After marking issues, recommend specific edits +5. Verify edits maintain the original intent — re-run the scorer; the Flesch score should improve, not regress **After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact. @@ -264,6 +265,16 @@ For every statement, ask "Okay, so what?" If the copy doesn't answer that questi Use these for faster reviews when a full seven-sweep process isn't needed. +### AI-Pattern Check + +If the draft may be AI-generated (or AI-assisted), run the detector before editing: + +```bash +python3 scripts/ai_content_detector.py draft.md --json # no arg = --demo mode +``` + +It scores burstiness, vocabulary diversity, and stock-phrase density. A high AI-likelihood score means the piece needs **content-humanizer** treatment before copy editing — polishing AI mush produces polished AI mush. + ### Word-Level Checks **Cut these words:** diff --git a/marketing-skill/skills/copywriting/SKILL.md b/marketing-skill/skills/copywriting/SKILL.md index fa044eb6..cb6603bc 100644 --- a/marketing-skill/skills/copywriting/SKILL.md +++ b/marketing-skill/skills/copywriting/SKILL.md @@ -122,6 +122,15 @@ Puns and wit make copy memorable—but only if it fits the brand and doesn't und - "Never {unpleasant event} again" - "{Question highlighting main pain point}" +**Score every headline candidate** with the bundled scorer before picking one: + +```bash +python3 scripts/headline_scorer.py "Ship dashboards in minutes, not sprints" +python3 scripts/headline_scorer.py --file headlines.txt --json # batch-score a list +``` + +It rates 0-100 across 6 dimensions (length, specificity, power words, clarity, emotional pull, format). Write 5-10 candidates, score them all, present the top 2-3 with their scores and dimension breakdowns — never present a sub-60 headline as the primary recommendation. + **For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md) **For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md) diff --git a/marketing-skill/skills/email-sequence/SKILL.md b/marketing-skill/skills/email-sequence/SKILL.md index 064a1a57..aa6df3c3 100644 --- a/marketing-skill/skills/email-sequence/SKILL.md +++ b/marketing-skill/skills/email-sequence/SKILL.md @@ -74,6 +74,16 @@ What to measure and benchmarks --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Sequence analyzer | `python3 scripts/sequence_analyzer.py --file sequence.json` (no arg = embedded demo; `--json` for pipelines) | Sequence quality score 0-100: pacing, subject-line variety, CTA consistency, exit-condition coverage | + +Run it on the assembled sequence (export the per-email blocks above as a JSON array) before handing off: fix anything it flags below 70, then attach the final score to the Metrics Plan. + +--- + ## Task-Specific Questions 1. What triggers entry to this sequence? diff --git a/marketing-skill/skills/form-cro/SKILL.md b/marketing-skill/skills/form-cro/SKILL.md index cd62386f..bb41a434 100644 --- a/marketing-skill/skills/form-cro/SKILL.md +++ b/marketing-skill/skills/form-cro/SKILL.md @@ -43,7 +43,22 @@ Before providing recommendations, identify: --- ## Core Principles -→ See references/form-cro-playbook.md for details + +The thresholds that drive every form audit (full treatment in references/form-cro-playbook.md): + +- **Field count**: every added field costs conversions. Lead-gen forms: 3-5 fields is the working ceiling; 7+ required fields is a high-priority finding unless lead-qualification value is proven. +- **Required vs optional**: each *required* field must justify itself with a downstream use. "Nice for sales" is not a justification — make it optional or cut it. +- **High-friction fields**: phone number, company size, and address are the biggest abandonment drivers on top-of-funnel forms — demand justification or move them to step 2 / progressive profiling. +- **Error recovery**: inline validation on blur (not on submit), specific error copy ("Enter a work email" not "Invalid input"), never clear filled fields on error. +- **CTA**: value-specific button text ("Get my report") outperforms generic ("Submit"). + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Field analyzer | `python3 scripts/form_field_analyzer.py forms.json` (no arg = embedded demo; `--json` for pipelines) | Per-form field count, required-field ratio, high-friction field flags, CTA assessment | + +Run it on the form definition first; its flags become the seed list for the Form Audit below — each flag gets an Issue/Impact/Fix/Priority entry. ## Output Format diff --git a/marketing-skill/skills/free-tool-strategy/SKILL.md b/marketing-skill/skills/free-tool-strategy/SKILL.md index 5466871e..5e95c310 100644 --- a/marketing-skill/skills/free-tool-strategy/SKILL.md +++ b/marketing-skill/skills/free-tool-strategy/SKILL.md @@ -16,7 +16,7 @@ You are a growth engineer who has built and launched free tools that generated h ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/launch-strategy/SKILL.md b/marketing-skill/skills/launch-strategy/SKILL.md index 23951273..60b6cb76 100644 --- a/marketing-skill/skills/launch-strategy/SKILL.md +++ b/marketing-skill/skills/launch-strategy/SKILL.md @@ -21,7 +21,28 @@ If `.claude/product-marketing-context.md` exists, read it before asking question --- ## Core Philosophy -→ See references/launch-frameworks-and-checklists.md for details + +A launch is a momentum system, not a day. Two frameworks drive everything (full treatment in references/launch-frameworks-and-checklists.md): + +**ORB channel model** — map every launch action to one of three channel types: +- **Owned** — email list, blog, in-app. You control reach; activate first. +- **Rented** — social platforms, communities. Algorithmic reach; you play by their rules. +- **Borrowed** — partner audiences, newsletters, podcasts, Product Hunt. Other people's reach; requires relationship work weeks before launch day. + +A plan that covers only one channel type is incomplete — the quality bar is all three. + +**Phase model** — sequence the launch instead of betting on one day: +1. **Pre-launch** (2-6 weeks out): waitlist/early access, borrowed-channel outreach, asset production +2. **Launch day**: time-boxed checklist, all channels firing, founder availability for engagement +3. **Post-launch** (30 days): momentum content — comparison pages, case studies, roundup email, retargeting + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Readiness scorer | `python3 scripts/launch_readiness_scorer.py --checklist launch.json` (no arg = embedded demo; `--export-template` writes a blank checklist; `--json` for pipelines) | 0-100 readiness score by category with the weakest categories called out | + +Gate the launch date on it: score the checklist when planning starts and again one week out — launching below a passing score in the "owned channels ready" or "assets ready" categories means slipping the date, not hoping. ## Task-Specific Questions diff --git a/marketing-skill/skills/marketing-context/SKILL.md b/marketing-skill/skills/marketing-context/SKILL.md index 9cc9ee3a..9d803af5 100644 --- a/marketing-skill/skills/marketing-context/SKILL.md +++ b/marketing-skill/skills/marketing-context/SKILL.md @@ -13,7 +13,9 @@ metadata: You are an expert product marketer. Your goal is to capture the foundational positioning, messaging, and brand context that every other marketing skill needs — so users never repeat themselves. -The document is stored at `.agents/marketing-context.md` (or `marketing-context.md` in the project root). +The document is stored at `.claude/product-marketing-context.md` — the canonical path every marketing skill in this library reads. Always write to this path. + +> **Backward compatibility:** if you previously created `.agents/marketing-context.md` or a root-level `marketing-context.md`, move it to `.claude/product-marketing-context.md` so sibling skills can find it. ## How This Skill Works @@ -123,6 +125,18 @@ See `templates/marketing-context-template.md` for the full template. --- +## Validate the Result + +After writing (or updating) the context file, score its completeness: + +```bash +python3 scripts/context_validator.py .claude/product-marketing-context.md --json +``` + +It emits a 0-100 completeness score from required + optional section coverage. Below 70: go back to the interview and fill the missing sections before declaring the context "done" — sibling skills will silently degrade on an incomplete file. Re-run it during the freshness audit too. + +--- + ## Tips - **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?" @@ -147,7 +161,7 @@ Surface these without being asked: | When you ask for... | You get... | |---------------------|------------| -| "Set up marketing context" | Guided interview → complete `marketing-context.md` | +| "Set up marketing context" | Guided interview → complete `.claude/product-marketing-context.md` | | "Auto-draft from codebase" | Codebase scan → V1 draft for review | | "Update positioning" | Targeted update of differentiation + competitive sections | | "Add customer quotes" | Customer language section populated with verbatim phrases | diff --git a/marketing-skill/skills/marketing-demand-acquisition/SKILL.md b/marketing-skill/skills/marketing-demand-acquisition/SKILL.md index 07ab9db6..e1a21b1f 100644 --- a/marketing-skill/skills/marketing-demand-acquisition/SKILL.md +++ b/marketing-skill/skills/marketing-demand-acquisition/SKILL.md @@ -1,6 +1,6 @@ --- name: "marketing-demand-acquisition" -description: Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs for Series A+ startups scaling internationally. Use when planning marketing strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or startup marketing budgets. Covers multi-channel acquisition (Google Ads, LinkedIn Ads, Meta Ads), CAC analysis, MQL/SQL workflows, attribution modeling, technical SEO, and co-marketing partnerships for hybrid PLG/Sales-Led motions in EU/US/Canada markets. +description: Creates demand generation campaigns, optimizes paid ad spend across LinkedIn, Google, and Meta, develops SEO strategies, and structures partnership programs. Use when planning demand gen strategy, growth marketing, advertising campaigns, PPC optimization, lead generation, pipeline generation, or marketing budgets. Covers multi-channel acquisition (Google Ads, LinkedIn Ads, Meta Ads), CAC analysis, MQL/SQL workflows, attribution modeling, technical SEO, and co-marketing partnerships. Default calibration profile is a Series A+ B2B SaaS scaling internationally (EU/US/Canada, hybrid PLG/Sales-Led) — adapt benchmarks for other stages and motions rather than skipping the skill. triggers: - demand gen - demand generation @@ -22,7 +22,7 @@ metadata: author: Alireza Rezvani category: marketing domain: demand-generation - updated: 2025-01 + updated: 2026-06 --- # Marketing Demand & Acquisition @@ -78,7 +78,7 @@ Acquisition playbook for Series A+ startups scaling internationally (EU/US/Canad ``` utm_source={channel} // linkedin, google, meta utm_medium={type} // cpc, display, email -utm_campaign={campaign-id} // q1-2025-linkedin-enterprise +utm_campaign={campaign-id} // {qN-yyyy}-linkedin-enterprise utm_content={variant} // ad-a, email-1 utm_term={keyword} // [paid search only] ``` diff --git a/marketing-skill/skills/marketing-ops/SKILL.md b/marketing-skill/skills/marketing-ops/SKILL.md index 7e9aa06d..e4a7a180 100644 --- a/marketing-skill/skills/marketing-ops/SKILL.md +++ b/marketing-skill/skills/marketing-ops/SKILL.md @@ -16,7 +16,7 @@ You are a senior marketing operations leader. Your goal is to route marketing qu ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. +If `.claude/product-marketing-context.md` exists, read it. If it doesn't, recommend running the **marketing-context** skill first — everything works better with context. ## How This Skill Works @@ -47,8 +47,8 @@ User wants to assess their marketing → you run a cross-functional audit touchi ### SEO Pod | Trigger | Route to | NOT this | |---------|----------|----------| -| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not ai-seo (that's for AI search engines) | -| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **ai-seo** | Not seo-audit (that's traditional SEO) | +| "SEO audit," "technical SEO," "on-page SEO" | **seo-audit** | Not aeo (that's for AI answer engines) | +| "AI search," "ChatGPT visibility," "Perplexity," "AEO" | **aeo** | Not seo-audit (that's traditional SEO) | | "Schema markup," "structured data," "JSON-LD," "rich snippets" | **schema-markup** | | | "Site structure," "URL structure," "navigation," "sitemap" | **site-architecture** | | | "Programmatic SEO," "pages at scale," "template pages" | **programmatic-seo** | | @@ -71,6 +71,11 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Paid ads," "Google Ads," "Meta ads," "ad campaign" | **paid-ads** | Not ad-creative (that's for copy generation) | | "Ad copy," "ad headlines," "ad variations," "RSA" | **ad-creative** | Not paid-ads (that's for strategy) | | "Social media strategy," "social calendar," "community" | **social-media-manager** | Not social-content (that's for individual posts) | +| "X growth," "Twitter growth," "grow my X account" | **x-twitter-growth** | Not social-content (that's cross-platform posts) | +| "YouTube," "video SEO," "channel strategy," "thumbnails" | **youtube-full** | Not video-content-strategist (that's platform-agnostic strategy) | +| "Video strategy," "short-form video," "video content plan" | **video-content-strategist** (sibling folder `video-content-strategist/`) | Not youtube-full (that's YouTube-specific + API-backed) | +| "Webinar," "webinar funnel," "registration rate," "show-up rate" | **webinar-marketing** | | +| "App Store," "Play Store," "ASO," "app keywords" | **app-store-optimization** | Not seo-audit (that's web search) | ### Growth Pod | Trigger | Route to | NOT this | @@ -87,12 +92,17 @@ User wants to assess their marketing → you run a cross-functional audit touchi | "Set up tracking," "GA4," "GTM," "event tracking" | **analytics-tracking** | Not campaign-analytics (that's for analysis) | | "Competitor page," "vs page," "alternative page" | **competitor-alternatives** | | | "Psychology," "persuasion," "behavioral science" | **marketing-psychology** | | +| "Analyze my social accounts," "engagement rate," "social audit" | **social-media-analyzer** | Not social-media-manager (that's planning, not analysis) | +| "Marketing prompts," "prompt templates," "LLM governance for marketing" | **prompt-engineer-toolkit** | | ### Sales & GTM Pod | Trigger | Route to | NOT this | |---------|----------|----------| | "Product launch," "feature announcement," "Product Hunt" | **launch-strategy** | | | "Pricing," "how much to charge," "pricing tiers" | **pricing-strategy** | | +| "Positioning," "ICP," "product marketing," "messaging framework" | **marketing-strategy-pmm** | Not copywriting (that's execution) | +| "Demand gen," "lead gen program," "MQL/SQL funnel," "CRM campaigns" | **marketing-demand-acquisition** | Not paid-ads (that's one channel) | +| "Brand guidelines," "brand consistency," "style guide audit" | **brand-guidelines** | Not marketing-context (that's the foundation doc) | ### Cross-Domain (route outside marketing-skill/) | Trigger | Route to | Domain | @@ -107,6 +117,14 @@ User wants to assess their marketing → you run a cross-functional audit touchi --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Campaign tracker | `python3 scripts/campaign_tracker.py campaign.json` (no arg = embedded sample; add `--json` for machine-readable) | Per-task status, owners, deadlines, overdue flags across the skills involved in a campaign | + +Use it during orchestration: after laying out a campaign sequence (below), capture each step as a task in a campaign JSON and run the tracker at every check-in — the overdue/ownerless flags feed the Quality Gate ("actions have owners and deadlines"). + ## Campaign Orchestration For multi-skill campaigns, follow this sequence: diff --git a/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py b/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py index e99edf2d..f29fa931 100644 --- a/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py +++ b/marketing-skill/skills/marketing-ops/scripts/campaign_tracker.py @@ -45,7 +45,7 @@ def analyze_campaign(campaign: dict) -> dict: pods_covered = set() pod_map = { "content": ["content-strategy", "copywriting", "copy-editing", "social-content", "marketing-ideas", "content-production", "content-humanizer", "content-creator"], - "seo": ["seo-audit", "programmatic-seo", "ai-seo", "schema-markup", "site-architecture"], + "seo": ["seo-audit", "programmatic-seo", "aeo", "schema-markup", "site-architecture"], "cro": ["page-cro", "form-cro", "signup-flow-cro", "onboarding-cro", "popup-cro", "paywall-upgrade-cro"], "channels": ["email-sequence", "cold-email", "paid-ads", "ad-creative", "social-media-manager"], "growth": ["ab-test-setup", "referral-program", "free-tool-strategy", "churn-prevention"], diff --git a/marketing-skill/skills/marketing-psychology/SKILL.md b/marketing-skill/skills/marketing-psychology/SKILL.md index 92af2dda..c7bf222f 100644 --- a/marketing-skill/skills/marketing-psychology/SKILL.md +++ b/marketing-skill/skills/marketing-psychology/SKILL.md @@ -16,7 +16,7 @@ You are an expert in applied behavioral science for marketing. Your job is to id ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. +If `.claude/product-marketing-context.md` exists, read it for audience personas and product positioning. Psychology works better when you know the audience. ## How This Skill Works diff --git a/marketing-skill/skills/marketing-skills/SKILL.md b/marketing-skill/skills/marketing-skills/SKILL.md index 801b09bc..ac73b166 100644 --- a/marketing-skill/skills/marketing-skills/SKILL.md +++ b/marketing-skill/skills/marketing-skills/SKILL.md @@ -1,105 +1,121 @@ --- name: "marketing-skills" -description: "42 marketing agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more coding agents. 7 pods: content, SEO, CRO, channels, growth, intelligence, sales. Foundation context + orchestration router. 27 Python tools (stdlib-only)." -version: 2.9.0 +description: "Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself." +version: 2.10.3 author: Alireza Rezvani license: MIT tags: - marketing - - seo - - content - - copywriting - - cro - - analytics - - ai-seo + - router + - index agents: - claude-code - codex-cli - openclaw --- -# Marketing Skills Division +# Marketing Skills — Directory + Router -42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer. +This is the index skill for the marketing plugin. It does one job: route you to the right specialist skill, then get out of the way. For request-by-request routing logic, [../marketing-ops/SKILL.md](../marketing-ops/SKILL.md) is the canonical router — this file is the map. -## Quick Start +**Counts (kept honest):** 44 specialist skills in `skills/` (plus this index and the deprecated `content-creator` redirect), 1 video skill in `video-content-strategist/`, 59 stdlib-only Python tools. No pip installs needed. -### Claude Code -``` -/read marketing-skill/skills/marketing-ops/SKILL.md -``` -The router will direct you to the right specialist skill. +## Start Here -### Codex CLI -```bash -codex --full-auto "Read marketing-skill/skills/marketing-ops/SKILL.md, then help me write a blog post about [topic]" -``` +1. **First run ever?** Use `skills/marketing-context/` to create `.claude/product-marketing-context.md`. Every other skill reads it for brand voice, personas, and competitive landscape. +2. **Know your task?** Find it in the route table below and load only that skill's `SKILL.md`. +3. **Ambiguous request?** Load `skills/marketing-ops/` — its routing matrix maps phrasings to skills. -### OpenClaw -Skills are auto-discovered from the repository. Ask your agent for marketing help — it routes via `marketing-ops`. +## Route Table -## Architecture +All paths are relative to `marketing-skill/`. -``` -marketing-skill/ -├── marketing-context/ ← Foundation: brand voice, audience, goals -├── marketing-ops/ ← Router: dispatches to the right skill -│ -├── Content Pod (8) ← Strategy → Production → Editing → Social -├── SEO Pod (5) ← Traditional + AI SEO + Schema + Architecture -├── CRO Pod (6) ← Pages, Forms, Signup, Onboarding, Popups, Paywall -├── Channels Pod (5) ← Email, Ads, Cold Email, Ad Creative, Social Mgmt -├── Growth Pod (4) ← A/B Testing, Referrals, Free Tools, Churn -├── Intelligence Pod (4) ← Competitors, Psychology, Analytics, Campaigns -└── Sales & GTM Pod (2) ← Pricing, Launch Strategy -``` +### Foundation + Ops +| Task | Skill | +|---|---| +| Capture brand/product context (run first) | `skills/marketing-context/` | +| Route a request, plan campaigns, pick channels | `skills/marketing-ops/` | +| Demand gen programs, funnel + CRM ops | `skills/marketing-demand-acquisition/` | +| Positioning, ICP, product marketing strategy | `skills/marketing-strategy-pmm/` | +| Brand voice/visual consistency audits | `skills/brand-guidelines/` | -## First-Time Setup +### Content +| Task | Skill | +|---|---| +| Write blog posts, articles, guides | `skills/content-production/` | +| Plan what content to create | `skills/content-strategy/` | +| Edit copy (Seven Sweeps) | `skills/copy-editing/` | +| Fix AI-sounding content | `skills/content-humanizer/` | +| Landing/sales page copy | `skills/copywriting/` | +| Headlines, hooks, idea generation | `skills/marketing-ideas/` | +| Persuasion frameworks, mental models | `skills/marketing-psychology/` | -Run `marketing-context` to create your `marketing-context.md` file. Every other skill reads this for brand voice, audience personas, and competitive landscape. Do this once — it makes everything better. +### SEO + AEO +| Task | Skill | +|---|---| +| Traditional SEO audit | `skills/seo-audit/` | +| AI search citations (ChatGPT, Perplexity, AI Overviews) | `skills/aeo/` | +| Programmatic SEO at scale | `skills/programmatic-seo/` | +| Structured data / schema.org | `skills/schema-markup/` | +| Site structure, internal linking | `skills/site-architecture/` | -## Pod Overview +### CRO (conversion) +| Task | Skill | +|---|---| +| Landing/marketing page conversion | `skills/page-cro/` | +| Forms | `skills/form-cro/` | +| Signup flow | `skills/signup-flow-cro/` | +| Onboarding/activation | `skills/onboarding-cro/` | +| Popups/modals | `skills/popup-cro/` | +| Paywall/upgrade screens | `skills/paywall-upgrade-cro/` | +| A/B test design + sample size | `skills/ab-test-setup/` | -| Pod | Skills | Python Tools | Key Capabilities | -|-----|--------|-------------|-----------------| -| **Foundation** | 2 | 2 | Brand context capture, skill routing | -| **Content** | 8 | 5 | Strategy → production → editing → humanization | -| **SEO** | 5 | 2 | Technical SEO, AI SEO (AEO/GEO), schema, architecture | -| **CRO** | 6 | 0 | Page, form, signup, onboarding, popup, paywall optimization | -| **Channels** | 5 | 2 | Email sequences, paid ads, cold email, ad creative | -| **Growth** | 4 | 2 | A/B testing, referral programs, free tools, churn prevention | -| **Intelligence** | 4 | 4 | Competitor analysis, marketing psychology, analytics, campaigns | -| **Sales & GTM** | 2 | 1 | Pricing strategy, launch planning | -| **Standalone** | 4 | 9 | ASO, brand guidelines, PMM strategy, prompt engineering | +### Channels +| Task | Skill | +|---|---| +| Email sequences/drips | `skills/email-sequence/` | +| Cold outbound email | `skills/cold-email/` | +| Paid ads (Google/Meta/LinkedIn) | `skills/paid-ads/` | +| Ad creative + copy | `skills/ad-creative/` | +| Social calendar + management | `skills/social-media-manager/` | +| Platform-native social posts | `skills/social-content/` | +| X/Twitter growth | `skills/x-twitter-growth/` | +| YouTube (data + strategy) | `skills/youtube-full/` | +| Video content strategy | `video-content-strategist/` (sibling folder, own plugin) | +| Webinars (funnel math) | `skills/webinar-marketing/` | +| App Store / Play Store (ASO) | `skills/app-store-optimization/` | -## Python Tools (27 scripts) +### Growth +| Task | Skill | +|---|---| +| Launches (PH, HN, etc.) | `skills/launch-strategy/` | +| Pricing + packaging | `skills/pricing-strategy/` | +| Referral programs | `skills/referral-program/` | +| Free tools as acquisition | `skills/free-tool-strategy/` | +| Churn prevention | `skills/churn-prevention/` | -All scripts are stdlib-only (zero pip installs), CLI-first with JSON output, and include embedded sample data for demo mode. +### Intelligence + Sales Enablement +| Task | Skill | +|---|---| +| Campaign performance, attribution | `skills/campaign-analytics/` | +| Tracking plans, UTM, GA4 key events | `skills/analytics-tracking/` | +| Social account analysis | `skills/social-media-analyzer/` | +| Competitor/alternatives pages | `skills/competitor-alternatives/` | +| LLM prompt templates + governance for marketing teams | `skills/prompt-engineer-toolkit/` | + +## Python Tools + +Each skill documents its own tools in its SKILL.md (a "Tools" or workflow section with exact CLI lines). Invoke from the skill's folder: ```bash -# Content scoring -python3 marketing-skill/skills/content-production/scripts/content_scorer.py article.md - -# AI writing detection -python3 marketing-skill/skills/content-humanizer/scripts/humanizer_scorer.py draft.md - -# Brand voice analysis -python3 marketing-skill/skills/content-production/scripts/brand_voice_analyzer.py copy.txt - -# Ad copy validation -python3 marketing-skill/skills/ad-creative/scripts/ad_copy_validator.py ads.json - -# Pricing scenario modeling -python3 marketing-skill/skills/pricing-strategy/scripts/pricing_modeler.py - -# Tracking plan generation -python3 marketing-skill/skills/analytics-tracking/scripts/tracking_plan_generator.py +python3 skills//scripts/.py --help ``` -## Unique Features +All 59 scripts are stdlib-only; most run a demo with no args. -- **AI SEO (AEO/GEO/LLMO)** — Optimize for AI citation, not just ranking -- **Content Humanizer** — Detect and fix AI writing patterns with scoring -- **Context Foundation** — One brand context file feeds all 42 skills -- **Orchestration Router** — Smart routing by keyword + complexity scoring -- **Zero Dependencies** — All Python tools use stdlib only +## Rules + +- Load ONE specialist skill per task — never bulk-load. +- If `.claude/product-marketing-context.md` exists, read it before any marketing task. +- `content-creator` is deprecated — use `skills/content-production/`. +- Don't pip-install anything for these tools. diff --git a/marketing-skill/skills/onboarding-cro/SKILL.md b/marketing-skill/skills/onboarding-cro/SKILL.md index 57420cbe..a87536f0 100644 --- a/marketing-skill/skills/onboarding-cro/SKILL.md +++ b/marketing-skill/skills/onboarding-cro/SKILL.md @@ -164,14 +164,20 @@ Signup → Step 1 → Step 2 → Activation → Retention 100% 80% 60% 40% 25% ``` -Identify biggest drops and focus there. +Run the bundled analyzer on your step counts instead of eyeballing: + +```bash +python3 scripts/activation_funnel_analyzer.py funnel.json --json # no arg = embedded demo +``` + +It computes per-step drop-off, an activation score 0-100, and names the biggest-loss step. That step is where the audit focuses first. --- ## Output Format ### Onboarding Audit -For each issue: Finding → Impact → Recommendation → Priority +Lead with the analyzer's output: activation score + the named biggest-drop step. Then, for each issue: Finding → Impact → Recommendation → Priority ### Onboarding Flow Design - Activation goal diff --git a/marketing-skill/skills/page-cro/SKILL.md b/marketing-skill/skills/page-cro/SKILL.md index b4a10af1..656c86f7 100644 --- a/marketing-skill/skills/page-cro/SKILL.md +++ b/marketing-skill/skills/page-cro/SKILL.md @@ -108,9 +108,19 @@ Analyze the page across these dimensions, in order of impact: --- +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Conversion audit | `python3 scripts/conversion_audit.py --file page.html` (or `--url https://...`; `--json` for pipelines) | Mechanical scan for conversion signals: CTA presence/count, form weight, social proof, trust elements — with a score | + +Run it before the manual framework pass; its score anchors the audit and its flags seed the Quick Wins list. + +--- + ## Output Format -Structure your recommendations as: +Open with the `conversion_audit.py` score, then structure recommendations as: ### Quick Wins (Implement Now) Easy changes with likely immediate impact. diff --git a/marketing-skill/skills/paid-ads/SKILL.md b/marketing-skill/skills/paid-ads/SKILL.md index 9db02ffe..1e4e3b10 100644 --- a/marketing-skill/skills/paid-ads/SKILL.md +++ b/marketing-skill/skills/paid-ads/SKILL.md @@ -76,10 +76,10 @@ Account ``` [Platform]_[Objective]_[Audience]_[Offer]_[Date] -Examples: -META_Conv_Lookalike-Customers_FreeTrial_2024Q1 +Examples (use the current year/quarter — {YYYY}/{Qn} are placeholders): +META_Conv_Lookalike-Customers_FreeTrial_{YYYY}Q1 GOOG_Search_Brand_Demo_Ongoing -LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 +LI_LeadGen_CMOs-SaaS_Whitepaper_{MonYY} ``` ### Budget Allocation @@ -227,9 +227,19 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 ## Reporting & Analysis +### Tools + +| Tool | Invocation | Output | +|---|---|---| +| ROAS calculator | `python3 scripts/roas_calculator.py --spend 5000 --revenue 18000 --conversions 120 --clicks 2400 --margin 0.7` (or `--file metrics.json`; `--json` for pipelines) | ROAS, CPA, CPC, CVR, margin-adjusted ROAS + recommendations | +| Ad health scorer | `python3 scripts/ad_health_scorer.py --checks checks.json --platform meta` (no arg = `--demo`; `--json` for pipelines) | Weighted 0-100 account health score with severity-ranked findings; see [references/scoring-system.md](references/scoring-system.md) for the scoring model | + ### Weekly Review + +Run both tools on the week's numbers, then review: - Spend vs. budget pacing -- CPA/ROAS vs. targets +- CPA/ROAS vs. targets — from `roas_calculator.py`, margin-adjusted, not platform-reported +- Account health score trend — from `ad_health_scorer.py`; investigate any category that dropped - Top and bottom performing ads - Audience performance breakdown - Frequency check (fatigue risk) diff --git a/marketing-skill/skills/pricing-strategy/SKILL.md b/marketing-skill/skills/pricing-strategy/SKILL.md index 21d644bb..9fda84ea 100644 --- a/marketing-skill/skills/pricing-strategy/SKILL.md +++ b/marketing-skill/skills/pricing-strategy/SKILL.md @@ -18,7 +18,7 @@ Pricing is not math — it's positioning. The right price isn't the one that cov ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/marketing-skill/skills/programmatic-seo/SKILL.md b/marketing-skill/skills/programmatic-seo/SKILL.md index 3e8287a8..6cdfd1a1 100644 --- a/marketing-skill/skills/programmatic-seo/SKILL.md +++ b/marketing-skill/skills/programmatic-seo/SKILL.md @@ -128,7 +128,17 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Is it first-party, scraped, licensed, public? - How is it updated? -### 3. Template Design +### 3. URL Pattern Generation (bundled tool) + +Generate and sanity-check the URL space before building templates: + +```bash +python3 scripts/url_pattern_generator.py pattern.json --json # no arg = embedded demo +``` + +Give it the template (e.g., `{tool}-vs-{competitor}-comparison`), base URL, and variable lists; it expands the combinations, reports the page count, and flags slug problems. If the expansion produces more pages than you have unique data for (see step 2), cut variables — don't ship thin pages. + +### 4. Template Design **Page structure:** - Header with target keyword @@ -142,7 +152,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - Conditional content based on data - Original insights/analysis per page -### 4. Internal Linking Architecture +### 5. Internal Linking Architecture **Hub and spoke model:** - Hub: Main category page @@ -154,7 +164,7 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego"). - XML sitemap for all pages - Breadcrumbs with structured data -### 5. Indexation Strategy +### 6. Indexation Strategy - Prioritize high-volume patterns - Noindex very thin variations diff --git a/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md b/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md index 037d0b5d..c0613e72 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/SKILL.md @@ -1,6 +1,6 @@ --- name: "prompt-engineer-toolkit" -description: "Analyzes and rewrites prompts for better AI output, creates reusable prompt templates for marketing use cases (ad copy, email campaigns, social media), and structures end-to-end AI content workflows. Use when the user wants to improve prompts for AI-assisted marketing, build prompt templates, or optimize AI content workflows. Also use when the user mentions 'prompt engineering,' 'improve my prompts,' 'AI writing quality,' 'prompt templates,' or 'AI content workflow.'" +description: "Turns marketing prompts into tested, versioned production assets: A/B prompt evaluation against structured test cases, immutable prompt version history with diffs, ready-to-use marketing prompt templates (ad copy, email campaigns, social posts, landing pages, SEO meta), and an LLM-governance playbook for marketing teams (claim discipline, disclosure rules, human-review gates). Use when a marketing team relies on AI-generated content and needs prompt quality to be measurable and safe — or when the user mentions 'prompt engineering,' 'improve my prompts,' 'prompt templates,' 'prompt versioning,' 'AI content workflow,' or 'AI governance for marketing.'" license: MIT metadata: version: 1.0.0 @@ -106,9 +106,9 @@ python3 scripts/prompt_versioner.py changelog --name support_classifier ## References -- [references/prompt-templates.md](references/prompt-templates.md) -- [references/technique-guide.md](references/technique-guide.md) -- [references/evaluation-rubric.md](references/evaluation-rubric.md) +- [references/prompt-templates.md](references/prompt-templates.md) — 6 production marketing templates (ad copy, email sequence, social repurposing, landing sections, SEO meta, brand-voice rewrite) plus generic building blocks; each written to be graded by `prompt_tester.py` +- [references/technique-guide.md](references/technique-guide.md) — technique-selection table for marketing tasks + the LLM-governance stack for marketing teams (claim discipline, disclosure rules, data boundaries, human-review gates) +- [references/evaluation-rubric.md](references/evaluation-rubric.md) — mechanical scoring weights, acceptance gates, marketing quality dimensions, test-suite design, and eval anti-patterns - [README.md](README.md) ## Evaluation Design diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md b/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md index 24886d59..d0cfb5b5 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/evaluation-rubric.md @@ -1,14 +1,64 @@ -# Evaluation Rubric +# Evaluation Rubric for Marketing Prompts -Score each case on 0-100 via weighted criteria: +How to score prompt outputs deterministically with `scripts/prompt_tester.py`, and how to extend the mechanical score with marketing-specific quality dimensions a regex can't fully capture. The principle throughout: evidence over intuition — a prompt is "better" only if it scores better on a realistic, edge-case-rich suite (never a single cherry-picked output). -- Expected content coverage: +weight -- Forbidden content violations: -weight -- Regex/format compliance: +weight -- Output length sanity: +/-weight +## Layer 1 — Mechanical Score (what `prompt_tester.py` computes) -Recommended acceptance gates: +Score each test case 0-100 via weighted criteria: -- Average score >= 85 -- No case below 70 -- Zero critical forbidden-content hits +| Criterion | Direction | Typical weight | Test-case field | +|---|---|---|---| +| Expected content coverage | + | 40% | `expected_contains` | +| Forbidden content violations | − (hard penalty) | 30% | `forbidden_contains` | +| Regex/format compliance | + | 20% | `expected_regex` | +| Output length sanity | ± | 10% | min/max length | + +**Acceptance gates (promote a prompt only if all hold):** + +- Average score ≥ 85 across the suite +- No individual case below 70 +- Zero critical forbidden-content hits (brand-banned words, invented statistics markers, competitor names where disallowed, compliance terms — see governance guide) + +## Layer 2 — Marketing Quality Dimensions + +Encode as many of these as possible into Layer-1 fields; what remains needs human review on a sample (5-10 outputs per variant): + +| Dimension | Mechanical proxy | Human check | +|---|---|---| +| **Specificity** | `expected_regex` for digits/named entities | Is the specific claim *true* and sourced? | +| **Brand voice** | `forbidden_contains` lexicon-no list | Does it sound like us, not "an AI"? | +| **Claim safety** | forbidden superlatives ("best", "#1", "guaranteed") unless proof token present | Would legal/compliance sign off? | +| **Format fitness** | char-count regex per platform | Does it read natively on the platform? | +| **CTA quality** | required CTA token | Single clear action, value-phrased? | +| **Audience fit** | required pain-point/persona token | Would the named persona care? | + +Scoring scale for human review (per Hamel Husain's eval guidance, keep it binary where possible): pass/fail per dimension beats 1-5 ratings — raters agree more, and failures become new `forbidden_contains`/`expected_regex` entries, ratcheting the mechanical suite forward. + +## Building the Test Suite + +A marketing prompt suite needs at minimum: + +1. **Happy-path cases (3-5)** — typical inputs with complete variables +2. **Sparse-input cases (2-3)** — missing proof points, vague audience: the prompt must degrade safely (omit proof, ask, or flag) rather than fabricate +3. **Adversarial cases (2-3)** — inputs that bait policy violations: competitor disparagement requests, unverifiable claims supplied as "facts", off-brand tone requests +4. **Edge-format cases (1-2)** — very long inputs, non-English fragments, emoji-laden source content + +Failure analysis loop: every production failure (rejected ad, spam-flagged email, off-brand post) becomes a new test case before the prompt is edited — the marketing equivalent of regression-test-first. + +## Anti-Patterns + +- **Single-output judgment** — comparing one generation per prompt; sampling variance swamps prompt differences. Run every case ≥ 3 times or compare suite averages. +- **LLM-as-judge without calibration** — if you add a model-graded criterion, calibrate it against human labels on 20+ examples first and re-check periodically (judges drift with model versions). +- **Score-only promotion** — a +2 average that introduces one compliance violation is a regression, not an improvement. Violations gate, scores rank. +- **Frozen suite** — a suite that never grows stops catching new failure modes; tie suite growth to the failure-analysis loop above. + +--- + +## Citations (6 sources) + +1. Anthropic — "Define your success criteria" + "Create strong empirical evaluations" (docs.anthropic.com/en/docs/build-with-claude/define-success, /develop-tests): measurable criteria and graded test suites before prompt iteration +2. OpenAI Evals — open-source eval framework and registry patterns for templated, deterministic graders (github.com/openai/evals) +3. Hamel Husain — "Your AI Product Needs Evals" (hamel.dev/blog/posts/evals): unit-test-style assertions, failure-driven suite growth, binary human labels +4. Zheng et al. — "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena" (NeurIPS 2023): LLM-judge agreement rates and bias modes (position, verbosity) +5. Eugene Yan — "Patterns for Building LLM-based Systems & Products" (eugeneyan.com): eval-first development, guardrails as gates vs. scores as ranks +6. Liu et al. — "G-Eval: NLG Evaluation using GPT-4 with Better Human Alignment" (EMNLP 2023): criteria-decomposed grading for content quality dimensions diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md b/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md index 872669dc..16ea83fe 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/prompt-templates.md @@ -1,105 +1,140 @@ -# Prompt Templates +# Marketing Prompt Templates -## 1) Structured Extractor +Production-ready prompt templates for the marketing use cases this skill promises: ad copy, email campaigns, social media, landing pages, and SEO metadata. Each template is written to be testable with `scripts/prompt_tester.py` — explicit output format, explicit constraints, explicit exclusions — and versionable with `scripts/prompt_versioner.py` under the semantic name given. + +Design principles behind every template (see citations): role + goal up front, output schema explicit, constraints as bullets not prose, variables in `{{double_braces}}`, and a forbidden-content clause so `must_not_contain` checks have something to enforce. + +--- + +## 1) Ad Copy Variants — `ad_copy_shortform` ```text -You are an extraction assistant. -Return ONLY valid JSON matching this schema: -{{schema}} +You are a direct-response copywriter for {{brand}} ({{one_line_positioning}}). -Input: -{{input}} +Write {{count}} ad copy variants for {{platform}} promoting {{offer}}. + +Audience: {{audience}} — their #1 pain: {{pain_point}}. +Voice: {{voice_adjectives}}. Reading level: 7th grade. + +Hard constraints: +- Headline ≤ {{headline_limit}} characters; primary text ≤ {{body_limit}} characters +- Each variant uses a DIFFERENT angle: pain-led, outcome-led, proof-led, curiosity-led +- One specific, verifiable claim per variant ({{proof_points}}); never invent statistics +- No exclamation-point stacking, no "🚀", no "game-changing/revolutionary/unleash" + +Return JSON array: [{"angle":"...","headline":"...","primary_text":"...","cta":"..."}] ``` -## 2) Classifier +Test cases should assert character limits via `expected_regex` and ban the cliché list via `forbidden_contains`. + +## 2) Email Campaign Sequence — `email_campaign_writer` ```text -Classify input into one of: {{labels}}. -Return only the label. +You are a lifecycle email marketer for {{brand}}. -Input: {{input}} -``` +Write email {{n}} of {{total}} in a {{sequence_type}} sequence (goal: {{conversion_goal}}). +Reader context: {{what_they_did}} — they have NOT yet {{what_they_havent_done}}. -## 3) Summarizer - -```text -Summarize the input in {{max_words}} words max. -Focus on: {{focus_area}}. -Input: -{{input}} -``` - -## 4) Rewrite With Constraints - -```text -Rewrite for {{audience}}. Constraints: -- Tone: {{tone}} -- Max length: {{max_len}} -- Must include: {{must_include}} -- Must avoid: {{must_avoid}} +- Subject line ≤ 45 chars + preview text ≤ 90 chars; no spam-trigger words (free!!!, act now, limited time) +- Body 90-150 words, one idea, one CTA ({{cta_text}} → {{cta_url}}) +- Plain-text tone — write like a competent colleague, not a brand +- Reference the reader's situation in sentence 1; never open with "I hope this finds you well" -Input: +Return: +SUBJECT: ... +PREVIEW: ... +BODY: +... +CTA: ... +``` + +## 3) Social Media Post Set — `social_post_repurposer` + +```text +You are a social content editor. Repurpose the source content into {{count}} platform-native posts. + +Platforms: {{platforms}}. +Source: +{{source_content}} + +Per-platform rules: +- X: ≤ 280 chars, hook in first 8 words, max 1 hashtag, placed at the end +- LinkedIn: ≤ 1300 chars, line breaks every 1-2 sentences, no engagement-bait ("Agree?") +- Instagram: caption ≤ 150 words + 5 relevant hashtags at the end + +Every post must contain one specific detail (number, name, example) from the source. +Return JSON: [{"platform":"...","post":"...","specific_detail_used":"..."}] +``` + +## 4) Landing Page Section Copy — `landing_section_writer` + +```text +You are a conversion copywriter. Write the {{section}} section for a landing page. + +Product: {{product}} — for {{audience}} who want {{outcome}}. +Differentiator: {{differentiator}}. Proof available: {{proof_points}}. + +Constraints: +- Headline: specific outcome, ≤ 12 words, no category jargon +- Body: benefit-first, "you" language, ≤ 60 words +- Use ONLY the proof points provided; if none fit, omit proof rather than invent it +- CTA button: verb + value ("Get my report"), never "Submit"/"Learn more" + +Return markdown with HEADLINE / BODY / CTA blocks. +``` + +## 5) SEO Title + Meta Description — `seo_meta_writer` + +```text +You are an SEO editor. Write title tag + meta description for the page below. + +Primary keyword: {{keyword}} (must appear in title, near the front, naturally). +Search intent: {{intent}}. Page summary: {{summary}}. + +Constraints: +- Title ≤ 60 characters, no clickbait, no ALL CAPS, brand suffix " | {{brand}}" if it fits +- Meta description 150-160 characters, includes keyword once, ends with a reason to click +- Describe what the page actually contains — no promises the page doesn't keep + +Return JSON: {"title":"...","title_chars":N,"meta":"...","meta_chars":N} +``` + +## 6) Brand-Voice Content Rewrite — `brand_voice_rewriter` + +```text +You are {{brand}}'s editor. Rewrite the draft in our voice without changing facts or claims. + +Voice profile (from .claude/product-marketing-context.md): {{voice_profile}} +Words we use: {{lexicon_yes}}. Words we never use: {{lexicon_no}}. + +Constraints: +- Preserve every factual claim, number, and named source exactly +- Keep length within ±10% of the draft +- Flag (don't fix) any claim that lacks a source: [NEEDS SOURCE: ...] + +Draft: {{input}} ``` -## 5) QA Pair Generator +## 7) Generic Building Blocks + +The original toolkit templates (structured extractor, classifier, summarizer, constrained rewrite, persona rewrite, policy-compliance check, prompt critique) remain useful as building blocks for non-content marketing automation — lead triage, review mining, survey coding. Pattern: ```text -Generate {{count}} Q/A pairs from input. -Output JSON array: [{"question":"...","answer":"..."}] - -Input: -{{input}} -``` - -## 6) Issue Triage - -```text -Classify issue severity: P1/P2/P3/P4. -Return JSON: {"severity":"...","reason":"...","owner":"..."} -Input: -{{input}} -``` - -## 7) Code Review Summary - -```text -Review this diff and return: -1. Risks -2. Regressions -3. Missing tests -4. Suggested fixes - -Diff: -{{input}} -``` - -## 8) Persona Rewrite - -```text -Respond as {{persona}}. -Goal: {{goal}} -Format: {{format}} +Classify input into one of: {{labels}}. Return only the label. Input: {{input}} ``` -## 9) Policy Compliance Check +Compose them: e.g., review mining = extractor (pull quotes) → classifier (theme) → summarizer (theme digest). -```text -Check input against policy. -Return JSON: {"pass":bool,"violations":[...],"recommendations":[...]} -Policy: -{{policy}} -Input: -{{input}} -``` +--- -## 10) Prompt Critique +## Citations (6 sources) -```text -Critique this prompt for clarity, ambiguity, constraints, and failure modes. -Return concise recommendations and an improved version. -Prompt: -{{input}} -``` +1. Anthropic — Prompt engineering overview: role prompting, structured outputs, "be clear and direct" (docs.anthropic.com/en/docs/build-with-claude/prompt-engineering) +2. OpenAI — Prompt engineering guide: instructions-first, delimiters, reference text to limit fabrication (platform.openai.com/docs/guides/prompt-engineering) +3. Google — Gemini prompting strategies: task/context/format decomposition, few-shot examples (ai.google.dev/gemini-api/docs/prompting-strategies) +4. Brown et al. — "Language Models are Few-Shot Learners" (NeurIPS 2020): few-shot examples improve format adherence +5. DAIR.AI — Prompt Engineering Guide: technique taxonomy and template anatomy (promptingguide.ai) +6. Ethan Mollick — One Useful Thing essays on practitioner prompting patterns for business content (oneusefulthing.org) diff --git a/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md b/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md index 6ea0ae7f..fdbadfde 100644 --- a/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md +++ b/marketing-skill/skills/prompt-engineer-toolkit/references/technique-guide.md @@ -1,25 +1,61 @@ -# Technique Guide +# Technique Guide + LLM Governance for Marketing Teams -## Selection Rules +Two things in one reference: (1) which prompting technique to use for which marketing task, and (2) the governance layer — the rules a marketing team needs so AI-assisted content ships safely, legally, and on-brand at scale. -- Zero-shot: deterministic, simple tasks -- Few-shot: formatting ambiguity or label edge cases -- Chain-of-thought: multi-step reasoning tasks -- Structured output: downstream parsing/integration required -- Self-critique/meta prompting: prompt improvement loops +--- -## Prompt Construction Checklist +## Part 1: Technique Selection for Marketing Tasks -- Clear role and goal -- Explicit output format -- Constraints and exclusions -- Edge-case handling instruction -- Minimal token usage for repetitive tasks +| Technique | Use when | Marketing examples | +|---|---|---| +| **Zero-shot + tight constraints** | Task is well-specified and format is simple | SEO meta tags, UTM naming, subject lines | +| **Few-shot (2-5 examples)** | Voice/format is hard to describe but easy to show | Brand-voice posts, email tone, ad-angle patterns — paste your 3 best-performing examples | +| **Chain-of-thought / plan-then-write** | Multi-step reasoning before output | Campaign briefs (audience → angle → channel → copy), positioning drafts | +| **Structured output (JSON/schema)** | Output feeds another tool or script | Ad variant sets, calendar entries, anything `prompt_tester.py` will grade by regex | +| **Decomposition (prompt chains)** | One mega-prompt underperforms | Research → outline → draft → brand-voice rewrite → compliance check, each step testable separately | +| **Self-critique pass** | Quality gate before human review | "List 3 weaknesses of this draft against the brief, then fix them" | -## Failure Pattern Checklist +**Construction checklist** (every marketing prompt): explicit role + goal; the audience and their pain named; output format with limits (chars/words); constraints as bullets; a forbidden list (clichés, banned claims, competitor names); instruction for missing inputs ("if no proof point fits, omit proof — never invent"). -- Too broad objective -- Missing output schema -- Contradictory constraints -- No negative examples for unsafe behavior -- Hidden assumptions not stated in prompt +**Failure patterns to check before testing:** objective too broad ("write something engaging"); missing output schema; contradictory constraints (casual tone + formal compliance phrasing in one prompt); no negative instructions, so the model fills gaps with invented stats; hidden assumptions (brand voice referenced but not provided — pass the actual voice profile from `.claude/product-marketing-context.md`). + +--- + +## Part 2: LLM Governance for Marketing + +Marketing is a high-exposure surface for AI failure: invented statistics in ads, undisclosed AI-generated endorsements, off-brand tone at scale, and privacy violations in personalization. Governance turns those from incidents into checklist items. + +### The Governance Stack + +1. **Approved-use registry** — every production prompt lives in `prompt_versioner.py` with a named owner, author history, and change notes. No anonymous prompt edits in production workflows. +2. **Pre-deployment evaluation** — no prompt ships without passing its test suite (see evaluation-rubric.md). Model upgrades re-run the full baseline suite before switchover — a model swap is a change event. +3. **Claim discipline** — generated copy may only use claims from a maintained proof-point list. Test suites enforce this with `forbidden_contains` (superlatives, "guaranteed", unverifiable "%" patterns without a source token). A human verifies any new claim before it enters the proof list. +4. **Disclosure rules** — know where AI-generation disclosure is required: FTC rules cover endorsements/testimonials (fake or AI-fabricated reviews are actionable); the EU AI Act (Art. 50) requires disclosure for certain AI-generated content including synthetic media; platforms (Meta, TikTok, YouTube) require labels on AI-generated/altered media in ads, especially political/social-issue ads. +5. **Data boundaries** — customer data in prompts is processing under GDPR/CCPA: no PII in third-party model calls without a processing basis and vendor DPA; segment-level personalization over individual-level wherever possible; never paste customer lists into ad-hoc chat sessions. +6. **Human-in-the-loop gates** — mechanical scores gate, humans approve: anything paid (ad spend), anything legal-sensitive (claims, pricing, comparisons), anything brand-new (first run of a new prompt) gets human review before publishing. Routine regenerations of an approved prompt+suite can ship on green scores. +7. **Incident loop** — rejected ads, spam-folder complaints, brand-voice misses: each becomes a test case (evaluation-rubric.md, failure analysis) and, if systemic, a prompt version bump with a changelog entry. + +### Roles + +| Role | Owns | +|---|---| +| Prompt owner (per workflow) | Template, test suite, version history | +| Marketing ops | Registry, model-change re-evaluation calendar | +| Legal/compliance reviewer | Claim list, disclosure map, escalation calls | +| Brand lead | Voice profile, lexicon-yes/no lists | + +### Minimum Viable Governance (small team) + +If the full stack is too heavy: (1) version every production prompt, (2) maintain the forbidden-claims list and wire it into `forbidden_contains`, (3) human-review everything paid, (4) re-run the suite on model changes. These four catch the expensive failures. + +--- + +## Citations (7 sources) + +1. NIST — AI Risk Management Framework 1.0 (2023) + Generative AI Profile (NIST-AI-600-1, 2024): govern/map/measure/manage functions adapted here to content workflows +2. FTC — "Rule on the Use of Consumer Reviews and Testimonials" (2024) and FTC Act §5 guidance on AI-generated endorsements and deceptive claims (ftc.gov) +3. EU AI Act — Regulation (EU) 2024/1689, Art. 50 transparency obligations for AI-generated and manipulated content +4. ISO/IEC 42001:2023 — AI management systems: registry, role assignment, and change-management discipline mirrored in the governance stack +5. Anthropic — Usage policies + prompt engineering docs on constraining model claims and structured outputs (anthropic.com/legal/aup, docs.anthropic.com) +6. Meta — Advertising Standards on AI-disclosure requirements for altered/generated media in ads (transparency.fb.com / Meta Business Help Center) +7. GDPR (Regulation 2016/679) Arts. 6, 28 — processing basis and processor agreements governing customer data sent to model vendors diff --git a/marketing-skill/skills/referral-program/SKILL.md b/marketing-skill/skills/referral-program/SKILL.md index b5ca0d80..64ac9b0d 100644 --- a/marketing-skill/skills/referral-program/SKILL.md +++ b/marketing-skill/skills/referral-program/SKILL.md @@ -16,7 +16,7 @@ You are a growth engineer who has designed referral and affiliate programs for S ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered. Gather this context (ask if not provided): diff --git a/marketing-skill/skills/schema-markup/SKILL.md b/marketing-skill/skills/schema-markup/SKILL.md index e3bc009f..5413b6d6 100644 --- a/marketing-skill/skills/schema-markup/SKILL.md +++ b/marketing-skill/skills/schema-markup/SKILL.md @@ -16,7 +16,7 @@ You are an expert in structured data and schema.org markup. Your goal is to help ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing. Gather this context: diff --git a/marketing-skill/skills/seo-audit/SKILL.md b/marketing-skill/skills/seo-audit/SKILL.md index 765808ae..df136359 100644 --- a/marketing-skill/skills/seo-audit/SKILL.md +++ b/marketing-skill/skills/seo-audit/SKILL.md @@ -38,14 +38,32 @@ Before auditing, understand: --- ## Audit Framework -→ See references/seo-audit-reference.md for details + +The audit walks three layers — technical (crawl/indexation/speed), on-page (titles, headings, internal links, keyword targeting), content (intent match, E-E-A-T, thin/duplicate pages). Full framework: references/seo-audit-reference.md. + +**Core Web Vitals pass/fail thresholds** (75th percentile of real-user data; full triage in references/cwv-thresholds.md): + +| Metric | Good | Needs improvement | Poor | +|---|---|---|---| +| LCP (Largest Contentful Paint) | ≤ 2.5s | 2.5-4.0s | > 4.0s | +| INP (Interaction to Next Paint) | ≤ 200ms | 200-500ms | > 500ms | +| CLS (Cumulative Layout Shift) | ≤ 0.1 | 0.1-0.25 | > 0.25 | + +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| On-page checker | `python3 scripts/seo_checker.py --file page.html` (or `--url https://...`; `--json`) | Scores a single page 0-100: title/meta/headings/links/images | +| Health scorer | `python3 scripts/seo_health_scorer.py --checks checks.json --industry saas` (no arg = `--demo`; industries: saas/ecommerce/local/publisher; `--json`) | Weighted 0-100 site health score across 7 categories | + +Run `seo_checker.py` on the key templates/pages during the on-page layer, and `seo_health_scorer.py` on the completed check matrix to produce the audit's headline score. ## Output Format ### Audit Report Structure **Executive Summary** -- Overall health assessment +- Overall health assessment — lead with the `seo_health_scorer.py` score and its weakest categories - Top 3-5 priority issues - Quick wins identified @@ -111,7 +129,7 @@ Same format as above ## Related Skills - **programmatic-seo** — WHEN: user wants to build SEO pages at scale after the audit identifies keyword gaps. WHEN NOT: don't use for diagnosing existing issues; stay in seo-audit mode. -- **ai-seo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. +- **aeo** — WHEN: user wants to optimize for AI answer engines (SGE, Perplexity, ChatGPT) in addition to traditional search. WHEN NOT: don't use for purely technical crawl/indexation issues. - **schema-markup** — WHEN: audit reveals missing structured data opportunities (FAQ, HowTo, Product, Review schemas). WHEN NOT: don't use as a standalone fix when core technical SEO is broken. - **site-architecture** — WHEN: audit uncovers poor internal linking, orphan pages, or crawl depth issues that need a structural redesign. WHEN NOT: don't involve when the audit scope is limited to on-page or content issues. - **content-strategy** — WHEN: audit reveals thin content, keyword gaps, or lack of topical authority requiring a content plan. WHEN NOT: don't use when the problem is purely technical (robots.txt, redirects, speed). diff --git a/marketing-skill/skills/signup-flow-cro/SKILL.md b/marketing-skill/skills/signup-flow-cro/SKILL.md index f0856087..e5b27c04 100644 --- a/marketing-skill/skills/signup-flow-cro/SKILL.md +++ b/marketing-skill/skills/signup-flow-cro/SKILL.md @@ -43,6 +43,14 @@ Before providing recommendations, understand: ## Core Principles → See references/signup-cro-playbook.md for details +## Tools + +| Tool | Invocation | Output | +|---|---|---| +| Funnel drop analyzer | `python3 scripts/funnel_drop_analyzer.py --steps funnel.json` (or `--stdin`; `--json` for pipelines; no arg = embedded demo) | Per-step drop-off %, the worst step named, and severity ranking | + +Feed it the step-by-step user counts (landing → form start → form complete → verify → done). The named worst step is where the audit starts; quantify each finding's Impact with its drop-off number. + ## Output Format ### Audit Findings diff --git a/marketing-skill/skills/site-architecture/SKILL.md b/marketing-skill/skills/site-architecture/SKILL.md index ef070b25..faeced3c 100644 --- a/marketing-skill/skills/site-architecture/SKILL.md +++ b/marketing-skill/skills/site-architecture/SKILL.md @@ -16,7 +16,7 @@ You are an expert in website information architecture and technical SEO structur ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Gather this context: diff --git a/marketing-skill/skills/social-media-analyzer/SKILL.md b/marketing-skill/skills/social-media-analyzer/SKILL.md index f3f1fae3..85f23b65 100644 --- a/marketing-skill/skills/social-media-analyzer/SKILL.md +++ b/marketing-skill/skills/social-media-analyzer/SKILL.md @@ -1,6 +1,6 @@ --- name: "social-media-analyzer" -description: Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. +description: Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use when analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards. Also use when the user mentions "social media audit," "engagement rate," or "which platform performs best." triggers: - analyze social media - calculate engagement rate diff --git a/marketing-skill/skills/social-media-manager/SKILL.md b/marketing-skill/skills/social-media-manager/SKILL.md index 9ee9afa9..0acb4aa5 100644 --- a/marketing-skill/skills/social-media-manager/SKILL.md +++ b/marketing-skill/skills/social-media-manager/SKILL.md @@ -16,7 +16,7 @@ You are a senior social media strategist who has grown accounts from zero to six ## Before Starting **Check for marketing context first:** -If `marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. +If `.claude/product-marketing-context.md` exists, read it for brand voice, audience personas, and goals. Only ask for what's missing. Gather this context (ask if not provided): @@ -92,6 +92,14 @@ The 10% promotional cap is intentional. If your feed feels like an ad channel, p | Thu | Educational | Thread or how-to | Deep-dive content | | Fri | Social Proof or Promo | Case study or launch | End-of-week conversion focus | +### Generate the Calendar (bundled tool) + +```bash +python3 scripts/social_calendar_generator.py --config calendar.json --start 2026-06-15 --weeks 4 --markdown +``` + +Give it your pillars + platforms + cadence (no config = embedded demo; `--json` for pipelines); it emits a calendar with balanced pillar distribution. Use its output as the working calendar for the batch workflow below — rebalance manually only when a campaign (launch, event) needs to override a pillar slot. + ### Batch Creation Workflow ``` diff --git a/marketing-skill/skills/webinar-marketing/SKILL.md b/marketing-skill/skills/webinar-marketing/SKILL.md index 377bd2bf..011d5353 100644 --- a/marketing-skill/skills/webinar-marketing/SKILL.md +++ b/marketing-skill/skills/webinar-marketing/SKILL.md @@ -18,7 +18,7 @@ A webinar is a funnel, not an event. Registrations are cheap; attention and acti ## Before Starting **Check for context first:** -If `marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. +If `.claude/product-marketing-context.md` exists, read it before asking questions. Use it for brand voice, audience personas, and customer language, and only ask for what's specific to this event. Gather this context (ask conversationally, one section at a time — don't dump every question at once): diff --git a/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md b/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md index a94a6f92..700415a6 100644 --- a/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md +++ b/marketing-skill/video-content-strategist/skills/video-content-strategist/SKILL.md @@ -13,7 +13,7 @@ Video is the highest-trust content format. A viewer who watches 10 minutes of yo ## Before Starting -**Check for context first:** If marketing-context.md exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. +**Check for context first:** If `.claude/product-marketing-context.md` exists, read it before asking questions. It contains brand voice, audience, competitor analysis, and existing content assets. Gather this context (ask in one shot): diff --git a/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md b/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md index f38f44d8..759d689f 100644 --- a/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md +++ b/product-team/agile-product-owner/skills/agile-product-owner/SKILL.md @@ -1,6 +1,6 @@ --- name: "agile-product-owner" -description: Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use for writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing backlog. +description: Agile product ownership for backlog management and sprint execution. Covers user story writing, acceptance criteria, sprint planning, and velocity tracking. Use when writing user stories, creating acceptance criteria, planning sprints, estimating story points, breaking down epics, or prioritizing the backlog. not_for: Kanban-only workflows, waterfall project planning, general task management, non-Scrum agile frameworks (SAFe, LeSS) without adaptation triggers: - write user story diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md b/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md index e50fe4cf..d2c9be6a 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/SKILL.md @@ -1,90 +1,108 @@ --- name: apple-hig-expert -description: "Expert guidance on Apple Human Interface Guidelines (HIG). Covers iOS, macOS, and visionOS with 2026 Liquid Glass aesthetics and accessibility-first design." +description: "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')." license: MIT metadata: - version: 1.0.0 + version: 1.1.0 author: Alireza Rezvani category: design - updated: 2026-04-09 + updated: 2026-06-11 --- # Apple HIG Expert -You are a Senior Apple Design Lead with decades of experience shipping award-winning apps on the App Store. Your goal is to help users design and audit apps that feel natively integrated into the Apple ecosystem while pushing the boundaries of the **Liquid Glass** aesthetic. +Design and audit apps against the Apple Human Interface Guidelines (HIG, [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines)), including the **Liquid Glass** design language. HIG content evolves with each OS release — when a claim matters, verify against the live HIG pages cited in `references/`. ## Before Starting -**Check for context first:** -If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. +If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. Then gather: -Gather this context: -1. **Platform Target**: iOS, macOS, watchOS, or visionOS? -2. **Current State**: New project or auditing an existing mockup? -3. **App Category**: Utility, Productivity, Game, Social, etc.? +1. **Platform target**: iOS, macOS, watchOS, or visionOS? +2. **Current state**: new design or auditing an existing mockup/code? +3. **App category**: utility, productivity, game, social, etc. -## How This Skill Works +## Modes -This skill supports 2 primary modes: +- **Mode 1 — Design from scratch**: pick the platform navigation paradigm and layout primitives first (see `references/platform-specifics.md`), then apply typography and semantic color (`references/visual-design.md`). +- **Mode 2 — HIG audit**: fill in `templates/hig-audit-template.md`, run `scripts/hig_checker.py` on every measurable element, and deliver a scored report (see Worked example below). -### Mode 1: Design from Scratch -When starting fresh. Focus on atomic design, layout primitives, and navigation paradigms that align with Apple's core philosophies (Clarity, Deference, Depth). +## The Compliance Tool -### Mode 2: HIG Audit -When reviewing mockups or code. Use the [templates/hig-audit-template.md](templates/hig-audit-template.md) to systematically identify violations and refinement opportunities. +`scripts/hig_checker.py` (stdlib-only) has three subcommands: -## Core Design Principles (2026) +```bash +# 1. Contrast ratio (WCAG formula; pass >= 4.5:1 for normal text) +python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF" +# -> Contrast Ratio: 3.26 [FAILED] -### 1. Liquid Glass Aesthetic -Modern Apple design emphasizes translucency and fluid motion. -- **Translucency**: Use materials (thin, thick, ultra-thin) to create hierarchy. -- **Depth**: Layers should reflect z-axis relationships. -- **Fluidity**: Interactions should feel like physical objects responding to touch/eyes. +# 2. Tap-target size (pass >= 44x44 pt per HIG) +python3 scripts/hig_checker.py target 32 32 +# -> Tap Target: 32x32 [FAILED] -### 2. Accessibility First -Design for everyone from Day 1. -- **VoiceOver**: All elements must have semantic descriptions. -- **Tap Targets**: Minimum 44x44 points for all interactive elements. -- **Contrast**: Ensure legibility against translucent backgrounds. +# 3. Batch audit from JSON -> scorecard (starts at 100, -10 per violation) +python3 scripts/hig_checker.py batch audit.json +``` -## Workflows +Batch input shape: -### Phase 1: Navigation & Layout -Choose the right navigation pattern (Sidebars for macOS, Tab Bars for iOS, Ornaments for visionOS). -See [references/platform-specifics.md](references/platform-specifics.md) for details. +```json +{ + "checks": [ + {"type": "contrast", "name": "caption-on-card", "fg": "#8E8E93", "bg": "#FFFFFF"}, + {"type": "target", "name": "close-button", "w": 32, "h": 32} + ] +} +``` -### Phase 2: Visual Styling -Apply typography (San Francisco family) and semantic colors. -See [references/visual-design.md](references/visual-design.md). +**Scorecard rubric:** the batch score starts at 100 and subtracts 10 per failed check; violations are listed by element name. 90-100 = ship, 70-80 = fix before release, below 70 = systematic rework. Checks the tool cannot measure (VoiceOver labels, Dynamic Type behavior, Reduce Transparency) are assessed manually via the audit template and tagged with confidence. -### Phase 3: Final Audit -Run the `hig_checker.py` tool to automate contrast and layout checks. +## Worked example: iOS settings-screen audit + +**Input:** mockup with body text `#1C1C1E` and captions `#8E8E93` on white cards, a 32x32 pt close button, and a 343x50 pt primary CTA. + +**Run:** + +```bash +python3 scripts/hig_checker.py batch audit.json +``` + +**Output (real):** + +```json +{ + "score": 80, + "violations": [ + "Contrast 3.26 fails for caption-on-card", + "Target 32x32 small for close-button" + ] +} +``` + +**Findings → fixes (bottom line first):** + +> **HIG score 80/100 — two fixes before release.** +> 1. Captions fail contrast (3.26 < 4.5). Use `.secondaryLabel` (semantic color) instead of hardcoded `#8E8E93`, or darken to ≥ `#6E6E73` on white. 🟢 verified by tool. +> 2. Close button is 32x32 pt (< 44x44 minimum). Keep the glyph small but expand the hit region to 44x44 with padding/`contentShape`. 🟢 verified by tool. +> 3. Manual check: the card uses an ultra-thin material over a photo background — re-test caption contrast against the *busiest* underlying region and with Reduce Transparency on. 🟡 needs device test. + +## Core Design Principles + +1. **Liquid Glass** — translucent material hierarchy (announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, visionOS 26). In SwiftUI, apply it via the `glassEffect` view modifier; keep hierarchy between content and controls. See `references/visual-design.md`. +2. **Accessibility first** — VoiceOver labels on every element, 44x44 pt minimum targets, 4.5:1 contrast for normal text (3:1 large text), Dynamic Type support. See `references/accessibility.md`. +3. **Platform ergonomics** — tab bars/thumb reach on iOS, sidebars + menu bar + shortcuts on macOS, ornaments + gaze states on visionOS, glanceable vertical layouts on watchOS. See `references/platform-specifics.md`. ## Proactive Triggers -Surface these issues WITHOUT being asked: -- **Low Contrast**: Translucent layers masking text legibility. -- **Tiny Targets**: Interactive elements smaller than 44pt. -- **Missing Semantics**: Buttons with icons but no accessibility labels. -- **Density Overload**: Layouts that ignore white space/deference. - -## Output Artifacts - -| When you ask for... | You get... | -|---------------------|------------| -| "Audit my iOS app" | Detailed HIG Scorecard (0-100) with prioritized fixes. | -| "Design a visionOS ornament" | Spatial design specs with depth and gaze-contingent hover rules. | -| "Accessibility check" | Compliance report for VoiceOver, Dynamic Type, and Contrast. | +Surface these WITHOUT being asked: low contrast over translucent layers; interactive elements under 44 pt; icon buttons with no accessibility label; density overload (no breathing room between glass layers). ## Communication -All output follows the structured communication standard: -- **Bottom line first** — HIG compliance status before the details. -- **What + Why + How** — e.g., "Increase padding (What) because targets are too small (Why). Use 12pt margins (How)." -- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed. +- **Bottom line first** — compliance status before details. +- **What + Why + How** — "Expand the hit region (What) because 32 pt targets fail the HIG minimum (Why); pad to 44x44 via contentShape (How)." +- **Confidence tagging** — 🟢 tool-verified / 🟡 needs device test / 🔴 assumed. ## Related Skills -- **ui-design-system**: For creating token-based components. NOT for platform-specific HIG rules. -- **ux-researcher-designer**: For persona validation. NOT for visual styling. -- **landing-page-generator**: For web-based marketing pages. +- **ui-design-system**: token-based component systems (not platform HIG rules). +- **ux-researcher-designer**: persona/research validation (not visual styling). +- **landing-page-generator**: web marketing pages, not native apps. diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md index aa32e44e..f6fa5422 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/accessibility.md @@ -44,3 +44,12 @@ Apps must respond to system-wide font size changes. - [ ] Is every icon labeled for VoiceOver? - [ ] Does the layout remain usable at the largest Dynamic Type size? - [ ] Have you tested with "Reduce Transparency" enabled in system settings? + + +## Sources + +- Apple HIG — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility +- Apple HIG — Buttons (44x44 pt minimum hit region): https://developer.apple.com/design/human-interface-guidelines/buttons +- Apple HIG — Typography (Dynamic Type text styles): https://developer.apple.com/design/human-interface-guidelines/typography +- Apple Accessibility for developers: https://developer.apple.com/accessibility/ +- WCAG 2.x contrast minimums (4.5:1 / 3:1), which the HIG color guidance mirrors: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md index 1f8f78ef..3a80e17d 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/platform-specifics.md @@ -36,3 +36,13 @@ Designed for "Glances" — 2 to 5 second interactions. | **Input** | Touch / Voice | Mouse / Trackpad / Keys | Eyes (Gaze) / Hands | | **Typical Dist.** | 6 - 12 inches | 18 - 30 inches | Infinite (Arm's length) | | **Aesthetic** | High density | High precision | Spatially grounded | + + +## Sources + +- Apple HIG — Designing for iOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-ios +- Apple HIG — Designing for macOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-macos +- Apple HIG — Designing for visionOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos +- Apple HIG — Designing for watchOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos +- Apple HIG — Ornaments (visionOS): https://developer.apple.com/design/human-interface-guidelines/ornaments +- Apple HIG — Live Activities / Dynamic Island: https://developer.apple.com/design/human-interface-guidelines/live-activities diff --git a/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md b/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md index e95f4cdb..c8c088cf 100644 --- a/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md +++ b/product-team/apple-hig-expert/skills/apple-hig-expert/references/visual-design.md @@ -1,6 +1,6 @@ # Visual Design Guide (Liquid Glass 2026) -This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** aesthetic introduced in late 2025. +This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** design language — announced at WWDC25 (June 9, 2025) and shipped in September 2025 with iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, and visionOS 26. In SwiftUI it is applied with the `glassEffect` view modifier. ## Core Aesthetic: Liquid Glass @@ -35,9 +35,11 @@ Apple uses the **San Francisco (SF)** family across all platforms. | Variant | Platform | Usage | |---------|----------|-------| | **SF Pro** | iOS, macOS | System standard for performance and legibility. | -| **SF Compact** | watchOS | Optimized for small screens. | -| **SF Camera** | iOS | Wide-set variant used in Camera interfaces. | -| **SF Mono** | Dev Tools | Monospaced variant for code. | +| **SF Compact** | watchOS | Optimized for small screens (the Camera app uses SF Compact Rounded as of iOS 26). | +| **SF Mono** | Dev tools | Monospaced variant for code. | +| **New York** | All | Serif companion family for editorial contexts. | + +Only the families on [developer.apple.com/fonts](https://developer.apple.com/fonts/) (SF Pro, SF Compact, SF Mono, SF Arabic/Hebrew and other language extensions, New York) are available to developers. "SF Camera" was an internal face used in Apple's Camera app, never a public download — do not specify it in design systems. ### Dynamic Type You MUST support Dynamic Type. @@ -54,3 +56,14 @@ All spacing should be increments of 8 (8pt, 16pt, 24pt, 32pt). ### Margin Logic - **iOS**: Match the Dynamic Island or Safe Area insets. - **watchOS**: Maximize the bezel-less display by using rounded corner layouts. + + +## Sources + +- Apple HIG — Materials: https://developer.apple.com/design/human-interface-guidelines/materials +- Apple HIG — Typography: https://developer.apple.com/design/human-interface-guidelines/typography +- Apple HIG — Color: https://developer.apple.com/design/human-interface-guidelines/color +- Apple HIG — Layout: https://developer.apple.com/design/human-interface-guidelines/layout +- Apple Fonts (official SF/New York downloads): https://developer.apple.com/fonts/ +- "Meet Liquid Glass" (WWDC25 session 219): https://developer.apple.com/videos/play/wwdc2025/219/ +- Apple Newsroom, June 9 2025 — new software design announcement: https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/ diff --git a/product-team/code-to-prd/skills/code-to-prd/SKILL.md b/product-team/code-to-prd/skills/code-to-prd/SKILL.md index 3014a0a4..f9602518 100644 --- a/product-team/code-to-prd/skills/code-to-prd/SKILL.md +++ b/product-team/code-to-prd/skills/code-to-prd/SKILL.md @@ -1,25 +1,14 @@ --- -Name: code-to-prd -Tier: STANDARD -Category: product -Dependencies: none -Author: Alireza Rezvani -Version: 2.1.2 name: code-to-prd -description: | - Reverse-engineer any codebase into a complete Product Requirements Document (PRD). - Analyzes routes, components, state management, API integrations, and user interactions to produce - business-readable documentation detailed enough for engineers or AI agents to fully reconstruct - every page and endpoint. Works with frontend frameworks (React, Vue, Angular, Svelte, Next.js, Nuxt), - backend frameworks (NestJS, Django, Express, FastAPI), and fullstack applications. - - Trigger when users mention: generate PRD, reverse-engineer requirements, code to documentation, - extract product specs from code, document page logic, analyze page fields and interactions, - create a functional inventory, write requirements from an existing codebase, document API endpoints, - or analyze backend routes. +description: "Reverse-engineer any codebase into a complete Product Requirements Document (PRD). Analyzes routes, components, state management, API integrations, and user interactions to produce business-readable documentation detailed enough for engineers or AI agents to fully reconstruct every page and endpoint. Works with frontend frameworks (React, Vue, Angular, Svelte, Next.js, Nuxt), backend frameworks (NestJS, Django, Express, FastAPI), and fullstack applications. Use when users mention: generate PRD, reverse-engineer requirements, code to documentation, extract product specs from code, document page logic, analyze page fields and interactions, create a functional inventory, write requirements from an existing codebase, document API endpoints, or analyze backend routes." license: MIT metadata: updated: 2026-03-17 + tier: STANDARD + category: product + dependencies: none + author: Alireza Rezvani + version: 2.1.2 --- ## Name diff --git a/product-team/research-summarizer/skills/research-summarizer/SKILL.md b/product-team/research-summarizer/skills/research-summarizer/SKILL.md index 158fa53e..814900a1 100644 --- a/product-team/research-summarizer/skills/research-summarizer/SKILL.md +++ b/product-team/research-summarizer/skills/research-summarizer/SKILL.md @@ -19,13 +19,16 @@ Not a generic "summarize this" — a repeatable framework that extracts what mat --- -## Slash Commands +## Scope — Distinct From the research/ Domain -| Command | What it does | -|---------|-------------| -| `/research:summarize` | Summarize a single source into a structured brief | -| `/research:compare` | Compare 2-5 sources side-by-side with synthesis | -| `/research:cite` | Extract and format all citations from a document | +This skill summarizes **documents the user already has** (papers, articles, reports pasted or attached). It performs no web search and needs no MCP server. It is NOT: + +- `research/litreview` — academic literature *discovery* and review-guide generation (finds papers via Consensus/academic APIs) +- `research/dossier` — entity due-diligence built from live web research +- `research/notebooklm` — drives Google's NotebookLM product UI +- `research/research` — the router for open-ended "research [topic]" requests that require searching + +If the user asks you to *find* sources rather than digest supplied ones, route to the research/ domain instead. --- @@ -47,7 +50,7 @@ If the user has a document and wants structured understanding → this skill app ## Workflow -### `/research:summarize` — Single Source Summary +### Workflow 1 — Single Source Summary 1. **Identify source type** - Academic paper → use IMRAD structure (Introduction, Methods, Results, Analysis, Discussion) @@ -55,7 +58,7 @@ If the user has a document and wants structured understanding → this skill app - Technical report → use executive summary structure - Documentation → use reference summary structure -2. **Extract structured brief** +2. **Scaffold the brief** — `python3 scripts/format_summary.py --template academic` (or `article`/`report`/`executive` per source type), then fill in every section from the source: ``` Title: [exact title] Author(s): [names] @@ -89,7 +92,7 @@ If the user has a document and wants structured understanding → this skill app - Recency (when published, still relevant?) - Bias indicators (funding source, author affiliation, methodology gaps) -### `/research:compare` — Multi-Source Comparison +### Workflow 2 — Multi-Source Comparison 1. **Collect sources** (2-5 documents) 2. **Summarize each** using the single-source workflow above @@ -126,10 +129,10 @@ If the user has a document and wants structured understanding → this skill app [Based on weight of evidence, what should the reader believe/do?] ``` -### `/research:cite` — Citation Extraction +### Workflow 3 — Citation Extraction -1. **Scan document** for all references, footnotes, in-text citations -2. **Extract and format** using the requested style (APA 7 default) +1. **Run the extractor** — `python3 scripts/extract_citations.py document.txt --output json` detects DOI/URL/author-year/numbered citations and deduplicates them +2. **Review and format** the extracted list in the requested style (APA 7 default); manually catch citations the regex missed 3. **Classify citations** by type: - Primary sources (original research, data) - Secondary sources (reviews, meta-analyses, commentary) @@ -174,13 +177,12 @@ cat paper.txt | python3 scripts/extract_citations.py --stdin ### `scripts/format_summary.py` -CLI utility for generating structured research summaries. +CLI utility that emits **blank structured summary scaffolds** — you (the model) fill them in from the source. It does not analyze content itself. **Features:** -- Multiple summary templates (academic, article, report, executive) -- Configurable output length (brief, standard, detailed) -- Markdown and plain text output -- Key findings extraction with evidence tagging +- 6 templates: academic, article, report, executive, comparison, literature +- Configurable scaffold depth (brief, standard, detailed) +- Text and JSON output for downstream tooling **Usage:** ```bash @@ -254,7 +256,7 @@ git clone https://github.com/alirezarezvani/claude-skills.git cp -r claude-skills/product-team/research-summarizer ~/.claude/skills/ ``` -### Multi-tool install +### Multi-tool install (run from the claude-skills repo root) ```bash ./scripts/convert.sh --skill research-summarizer --tool codex|gemini|cursor|windsurf|openclaw ``` @@ -266,6 +268,18 @@ clawhub install cs-research-summarizer --- +## Verification Loop + +Before delivering any brief, check: + +1. Every Key Finding cites a location in the source (section, page, or quote) — no unanchored claims. +2. `python3 scripts/extract_citations.py --output json` exits 0 and its `total` matches the bibliography count in your output (investigate any gap). +3. Each source carries a 4-dimension quality rating (table above); weak sources are flagged, not silently included. +4. For comparisons: the matrix has one row per dimension and one column per source — no source skipped. +5. Nothing was invented: missing metadata is marked "not stated", never filled in. + +--- + ## Related Skills - **product-analytics** — Quantitative analysis. Complementary — use research-summarizer for qualitative sources, product-analytics for metrics. diff --git a/product-team/skills/product-manager-toolkit/SKILL.md b/product-team/skills/product-manager-toolkit/SKILL.md index 47747df0..c6c36b51 100644 --- a/product-team/skills/product-manager-toolkit/SKILL.md +++ b/product-team/skills/product-manager-toolkit/SKILL.md @@ -1,6 +1,6 @@ --- name: "product-manager-toolkit" -description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. +description: Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use when prioritizing features, synthesizing user research, writing requirement documentation, or developing product strategy. --- # Product Manager Toolkit diff --git a/product-team/skills/product-skills/SKILL.md b/product-team/skills/product-skills/SKILL.md index 806b87b0..6dc1e98b 100644 --- a/product-team/skills/product-skills/SKILL.md +++ b/product-team/skills/product-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "product-skills" -description: "10 product agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. PM toolkit (RICE), agile PO, product strategist (OKR), UX researcher, UI design system, competitive teardown, landing page generator, SaaS scaffolder, research summarizer. Python tools (stdlib-only)." +description: "Router/index for the 12 product skills bundled in this plugin (RICE prioritization, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding). Use when a product request doesn't obviously match one skill and you need to pick the right one (e.g., 'help me prioritize features', 'plan a product experiment')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -17,45 +17,45 @@ agents: - openclaw --- -# Product Team Skills +# Product Skills — Router -8 production-ready product skills covering product management, UX/UI design, and SaaS development. +This plugin bundles **12 product skills** (this router is the 13th folder under `product-team/skills/`). Each skill is self-contained: read its `SKILL.md`, run its `scripts/`, apply its `references/` and `assets/`. -## Quick Start +## Routing table -### Claude Code -``` -/read product-team/skills/product-manager-toolkit/SKILL.md -``` +Match the request against the signals below, then load `product-team/skills//SKILL.md`. If two or more rows match, ask the user one clarifying question before loading anything. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/product-team -``` +| Request signals | Skill | Path | +|---|---|---| +| Prioritize features, RICE scores, interview synthesis | product-manager-toolkit | `skills/product-manager-toolkit/` | +| OKRs, strategy cascade, objective alignment | product-strategist | `skills/product-strategist/` | +| Personas, usability findings, research synthesis | ux-researcher-designer | `skills/ux-researcher-designer/` | +| Design tokens, component specs, WCAG contrast | ui-design-system | `skills/ui-design-system/` | +| Competitor analysis, feature/pricing matrix | competitive-teardown | `skills/competitive-teardown/` | +| Retention, cohorts, funnel analysis | product-analytics | `skills/product-analytics/` | +| A/B test design, sample size, hypothesis gates | experiment-designer | `skills/experiment-designer/` | +| Opportunity trees, assumption mapping, discovery | product-discovery | `skills/product-discovery/` | +| Roadmap formats per audience, changelogs | roadmap-communicator | `skills/roadmap-communicator/` | +| Turn a written spec into a repo scaffold | spec-to-repo | `skills/spec-to-repo/` | +| Landing page (Next.js TSX + Tailwind) | landing-page-generator | `skills/landing-page-generator/` | +| Bootstrap a SaaS app skeleton | saas-scaffolder | `skills/saas-scaffolder/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Product Manager Toolkit | `product-manager-toolkit/` | RICE prioritization, customer discovery, PRDs | -| Agile Product Owner | `agile-product-owner/` | User stories, sprint planning, backlog | -| Product Strategist | `product-strategist/` | OKR cascades, market analysis, vision | -| UX Researcher Designer | `ux-researcher-designer/` | Personas, journey maps, usability testing | -| UI Design System | `ui-design-system/` | Design tokens, component docs, responsive | -| Competitive Teardown | `competitive-teardown/` | Systematic competitor analysis | -| Landing Page Generator | `landing-page-generator/` | Conversion-optimized pages | -| SaaS Scaffolder | `saas-scaffolder/` | Production SaaS boilerplate | - -## Python Tools - -9 scripts, all stdlib-only: +## Quick start ```bash -python3 ../product-manager-toolkit/scripts/rice_prioritizer.py --help -python3 ../product-strategist/scripts/okr_cascade_generator.py --help +# Example: route a prioritization request +cat product-team/skills/product-manager-toolkit/SKILL.md +python3 product-team/skills/product-manager-toolkit/scripts/rice_prioritizer.py --help ``` +## Related product-team plugins (packaged separately, not in this bundle) + +- `product-team/agile-product-owner/` — user stories, sprint capacity +- `product-team/code-to-prd/` — reverse-engineer a PRD from a codebase +- `product-team/apple-hig-expert/` — Apple HIG audits (Liquid Glass era) +- `product-team/research-summarizer/` — document summarization with citation extraction + ## Rules -- Load only the specific skill SKILL.md you need -- Use Python tools for scoring and analysis, not manual judgment +- Route to exactly one skill, then follow that skill's own workflow. +- This router ships no tools of its own — if no row matches, say so and ask rather than improvising. diff --git a/product-team/skills/ui-design-system/SKILL.md b/product-team/skills/ui-design-system/SKILL.md index 17612d6f..c36af38e 100644 --- a/product-team/skills/ui-design-system/SKILL.md +++ b/product-team/skills/ui-design-system/SKILL.md @@ -1,6 +1,6 @@ --- name: "ui-design-system" -description: UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration. +description: UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use when creating design systems, generating design tokens, maintaining visual consistency, or facilitating design-dev collaboration and developer handoff. --- # UI Design System diff --git a/product-team/skills/ux-researcher-designer/SKILL.md b/product-team/skills/ux-researcher-designer/SKILL.md index 51fa525f..b68b9cad 100644 --- a/product-team/skills/ux-researcher-designer/SKILL.md +++ b/product-team/skills/ux-researcher-designer/SKILL.md @@ -1,6 +1,6 @@ --- name: "ux-researcher-designer" -description: UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use for user research, persona creation, journey mapping, and design validation. +description: UX research and design toolkit for Senior UX Designer/Researcher including data-driven persona generation, journey mapping, usability testing frameworks, and research synthesis. Use when conducting user research, creating personas, mapping user journeys, planning usability tests, or validating designs. --- # UX Researcher & Designer diff --git a/productivity/email/skills/inbox-triage/SKILL.md b/productivity/email/skills/inbox-triage/SKILL.md index c28b2027..8d14a4dc 100644 --- a/productivity/email/skills/inbox-triage/SKILL.md +++ b/productivity/email/skills/inbox-triage/SKILL.md @@ -1,6 +1,6 @@ --- name: inbox-triage -description: "Runs a full inbox triage using the knowledge base created by the 'inbox-setup' skill. Light-intake by design (most invocations skip questions and run with KB-default preferences); asks at most 2 grill-me override questions when invocation is outside normal cadence or includes category-skip intent. Searches recent emails, classifies them via the user's taxonomy, researches new senders, generates recommendations, drafts replies (NEVER sends), delivers a report in the user's preferred format, and updates the knowledge base with learnings. Designed to run on a recurring schedule (1-3x daily) or on demand. Triggers: 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage', or any variation where the user wants their inbox processed. Requires the inbox-setup skill to have been run first." +description: "Runs a full inbox triage using the knowledge base created by the 'inbox-setup' skill. Light-intake by design (most invocations skip questions and run with KB-default preferences); asks at most 2 grill-me override questions when invocation is outside normal cadence or includes category-skip intent. Searches recent emails, classifies them via the user's taxonomy, researches new senders, generates recommendations, drafts replies (NEVER sends), delivers a report in the user's preferred format, and updates the knowledge base with learnings. Designed to run on a recurring schedule (1-3x daily) or on demand. Use when the user wants their inbox processed, in any variation (e.g., 'triage my inbox', 'inbox triage', 'check my email', 'run email triage', 'process my inbox', 'what's new in my email', 'handle my email', 'email triage'). Requires the inbox-setup skill to have been run first." license: MIT metadata: source_spec: "megaprompts/07-inbox-triage-megaprompt.md" diff --git a/project-management/skills/jira-expert/SKILL.md b/project-management/skills/jira-expert/SKILL.md index 26793f07..be10c8c8 100644 --- a/project-management/skills/jira-expert/SKILL.md +++ b/project-management/skills/jira-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "jira-expert" -description: Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use for Jira project setup, configuration, advanced search, dashboard creation, workflow design, and technical Jira operations. +description: Atlassian Jira expert for creating and managing projects, planning, product discovery, JQL queries, workflows, custom fields, automation, reporting, and all Jira features. Use when setting up or configuring Jira projects, writing JQL and advanced searches, creating dashboards, designing workflows, or performing technical Jira operations. --- # Atlassian Jira Expert diff --git a/project-management/skills/pm-skills/SKILL.md b/project-management/skills/pm-skills/SKILL.md index f6bcf3af..2aa4c2a1 100644 --- a/project-management/skills/pm-skills/SKILL.md +++ b/project-management/skills/pm-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "pm-skills" -description: "6 project management agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Senior PM, scrum master, Jira expert (JQL), Confluence expert, Atlassian admin, template creator. MCP integration for live Jira/Confluence automation." +description: "Router/index for the 8 project-management skills bundled in this plugin (senior PM quant toolkit, scrum master, Jira/JQL, Confluence, Atlassian admin, Atlassian templates, meeting analyzer, team communications). Use when a PM request doesn't obviously match one skill and you need to pick the right one (e.g., 'our sprints feel off', 'audit our Jira permissions'). Bundles an Atlassian Remote MCP config (.mcp.json) for live Jira/Confluence access." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -17,43 +17,34 @@ agents: - openclaw --- -# Project Management Skills +# Project Management Skills — Router -6 production-ready project management skills with Atlassian MCP integration. +This plugin bundles **8 PM skills** (this router is the 9th folder under `project-management/skills/`). Each skill is self-contained. The bundled `.mcp.json` wires the Atlassian Remote MCP (`https://mcp.atlassian.com/v1/sse`, OAuth handled by Claude Code). -## Quick Start +## Routing table -### Claude Code -``` -/read project-management/skills/jira-expert/SKILL.md -``` +Match the request, then load `project-management/skills//SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/project-management -``` +| Request signals | Skill | Path | +|---|---|---| +| Project health, risk EMV, three-point estimates | senior-pm | `skills/senior-pm/` | +| Sprint velocity, retro analysis, ceremony health | scrum-master | `skills/scrum-master/` | +| JQL queries, Jira workflows, boards | jira-expert | `skills/jira-expert/` | +| Confluence spaces, page structure, content audits | confluence-expert | `skills/confluence-expert/` | +| User/permission/scheme administration | atlassian-admin | `skills/atlassian-admin/` | +| Reusable Confluence/Jira templates | atlassian-templates | `skills/atlassian-templates/` | +| Meeting transcripts, talk-time, action items | meeting-analyzer | `skills/meeting-analyzer/` | +| Status updates, 3P updates, stakeholder comms | team-communications | `skills/team-communications/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Senior PM | `senior-pm/` | Portfolio management, risk analysis, resource planning | -| Scrum Master | `scrum-master/` | Velocity forecasting, sprint health, retrospectives | -| Jira Expert | `jira-expert/` | JQL queries, workflows, automation, dashboards | -| Confluence Expert | `confluence-expert/` | Knowledge bases, page layouts, macros | -| Atlassian Admin | `atlassian-admin/` | User management, permissions, integrations | -| Atlassian Templates | `atlassian-templates/` | Blueprints, custom layouts, reusable content | - -## Python Tools - -6 scripts, all stdlib-only: +## Quick start ```bash -python3 project-management/skills/senior-pm/scripts/project_health_dashboard.py --help -python3 project-management/skills/scrum-master/scripts/velocity_analyzer.py --help +# Example: route a sprint-health request +cat project-management/skills/scrum-master/SKILL.md +ls project-management/skills/scrum-master/scripts/ ``` ## Rules -- Load only the specific skill SKILL.md you need -- Use MCP tools for live Jira/Confluence operations when available +- Live Jira/Confluence operations go through the Atlassian Remote MCP (camelCase tool names such as `createJiraIssue`, `searchJiraIssuesUsingJql`, `createConfluencePage` — canonical list in `project-management/references/atlassian-mcp-tools.md`). Admin operations are NOT covered by the MCP — use admin.atlassian.com or the REST API per atlassian-admin. +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. diff --git a/ra-qm-team/README.md b/ra-qm-team/README.md index d47a2488..500c0a59 100644 --- a/ra-qm-team/README.md +++ b/ra-qm-team/README.md @@ -117,7 +117,6 @@ The 12 skills are organized across 5 strategic layers: ## 📦 Complete Skills Catalog ### 1. Senior Regulatory Affairs Manager (Head of Regulatory Affairs) -**Package:** `regulatory-affairs-head.zip` **Purpose:** Strategic regulatory leadership and cross-functional coordination for market access. @@ -147,7 +146,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 2. Senior Quality Manager Responsible Person (QMR) -**Package:** `quality-manager-qmr.zip` **Purpose:** Overall quality system responsibility and regulatory compliance oversight. @@ -177,7 +175,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 3. Senior Quality Manager - QMS ISO 13485 Specialist -**Package:** `quality-manager-qms-iso13485.zip` **Purpose:** ISO 13485 QMS implementation, maintenance, and optimization. @@ -207,7 +204,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 4. Senior CAPA Officer -**Package:** `capa-officer.zip` **Purpose:** Corrective and preventive action management within QMS. @@ -237,7 +233,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 5. Senior Quality Documentation Manager -**Package:** `quality-documentation-manager.zip` **Purpose:** Documentation control and review of all norms and appendices. @@ -267,7 +262,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 6. Senior Risk Management Specialist -**Package:** `risk-management-specialist.zip` **Purpose:** ISO 14971 risk management throughout product lifecycle. @@ -297,7 +291,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 7. Senior Information Security Manager (ISO 27001/27002) -**Package:** `information-security-manager-iso27001.zip` **Purpose:** ISMS implementation and cybersecurity compliance for medical devices. @@ -327,7 +320,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 8. Senior MDR 2017/745 Specialist -**Package:** `mdr-745-specialist.zip` **Purpose:** EU MDR compliance expertise and consulting. @@ -357,7 +349,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 9. Senior FDA Consultant and Specialist -**Package:** `fda-consultant-specialist.zip` **Purpose:** FDA submission pathways and QSR compliance. @@ -387,7 +378,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 10. Senior QMS Audit Expert -**Package:** `qms-audit-expert.zip` **Purpose:** Internal and external QMS auditing expertise. @@ -417,7 +407,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 11. Senior ISMS Audit Expert -**Package:** `isms-audit-expert.zip` **Purpose:** Information security management system auditing. @@ -447,7 +436,6 @@ The 12 skills are organized across 5 strategic layers: --- ### 12. Senior GDPR/DSGVO Expert -**Package:** `gdpr-dsgvo-expert.zip` **Purpose:** EU GDPR and German DSGVO compliance and auditing. @@ -495,14 +483,12 @@ The 12 skills are organized across 5 strategic layers: **Security & Privacy Focus?** → Focus on: Information Security Manager + GDPR Expert + ISMS Audit Expert -### Step 2: Download Skills +### Step 2: Get the Skills -Each skill is packaged as a .zip file for easy distribution: +Each skill is a self-contained folder under `ra-qm-team/skills/` (install via the `ra-qm-skills` marketplace plugin, or copy the folder directly): ```bash -# Extract a skill package -unzip regulatory-affairs-head.zip -cd regulatory-affairs-head +cd ra-qm-team/skills/regulatory-affairs-head # Explore the structure ls -la diff --git a/ra-qm-team/capa-officer.zip b/ra-qm-team/capa-officer.zip deleted file mode 100644 index c49397ae..00000000 Binary files a/ra-qm-team/capa-officer.zip and /dev/null differ diff --git a/ra-qm-team/fda-consultant-specialist.zip b/ra-qm-team/fda-consultant-specialist.zip deleted file mode 100644 index cd01e419..00000000 Binary files a/ra-qm-team/fda-consultant-specialist.zip and /dev/null differ diff --git a/ra-qm-team/gdpr-dsgvo-expert.zip b/ra-qm-team/gdpr-dsgvo-expert.zip deleted file mode 100644 index 502dfe7d..00000000 Binary files a/ra-qm-team/gdpr-dsgvo-expert.zip and /dev/null differ diff --git a/ra-qm-team/information-security-manager-iso27001.zip b/ra-qm-team/information-security-manager-iso27001.zip deleted file mode 100644 index 67ac1469..00000000 Binary files a/ra-qm-team/information-security-manager-iso27001.zip and /dev/null differ diff --git a/ra-qm-team/isms-audit-expert.zip b/ra-qm-team/isms-audit-expert.zip deleted file mode 100644 index 3a2c6976..00000000 Binary files a/ra-qm-team/isms-audit-expert.zip and /dev/null differ diff --git a/ra-qm-team/mdr-745-specialist.zip b/ra-qm-team/mdr-745-specialist.zip deleted file mode 100644 index f70440e9..00000000 Binary files a/ra-qm-team/mdr-745-specialist.zip and /dev/null differ diff --git a/ra-qm-team/qms-audit-expert.zip b/ra-qm-team/qms-audit-expert.zip deleted file mode 100644 index 14dc861c..00000000 Binary files a/ra-qm-team/qms-audit-expert.zip and /dev/null differ diff --git a/ra-qm-team/quality-documentation-manager.zip b/ra-qm-team/quality-documentation-manager.zip deleted file mode 100644 index cffd09af..00000000 Binary files a/ra-qm-team/quality-documentation-manager.zip and /dev/null differ diff --git a/ra-qm-team/quality-manager-qmr.zip b/ra-qm-team/quality-manager-qmr.zip deleted file mode 100644 index c4292685..00000000 Binary files a/ra-qm-team/quality-manager-qmr.zip and /dev/null differ diff --git a/ra-qm-team/quality-manager-qms-iso13485.zip b/ra-qm-team/quality-manager-qms-iso13485.zip deleted file mode 100644 index 508b7129..00000000 Binary files a/ra-qm-team/quality-manager-qms-iso13485.zip and /dev/null differ diff --git a/ra-qm-team/regulatory-affairs-head.zip b/ra-qm-team/regulatory-affairs-head.zip deleted file mode 100644 index 56c08de6..00000000 Binary files a/ra-qm-team/regulatory-affairs-head.zip and /dev/null differ diff --git a/ra-qm-team/risk-management-specialist.zip b/ra-qm-team/risk-management-specialist.zip deleted file mode 100644 index 303bb668..00000000 Binary files a/ra-qm-team/risk-management-specialist.zip and /dev/null differ diff --git a/ra-qm-team/skills/capa-officer/SKILL.md b/ra-qm-team/skills/capa-officer/SKILL.md index be868100..16c77f01 100644 --- a/ra-qm-team/skills/capa-officer/SKILL.md +++ b/ra-qm-team/skills/capa-officer/SKILL.md @@ -1,6 +1,6 @@ --- name: "capa-officer" -description: CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use for CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization. +description: CAPA system management for medical device QMS. Covers root cause analysis, corrective action planning, effectiveness verification, and CAPA metrics. Use when running CAPA investigations, 5-Why analysis, fishbone diagrams, root cause determination, corrective action tracking, effectiveness verification, or CAPA program optimization. triggers: - CAPA investigation - root cause analysis diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md b/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md index 8b6f989f..7a9bb26b 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "gdpr-dsgvo-expert" -description: GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests. Use for GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, and data subject rights management. +description: GDPR and German DSGVO compliance automation. Scans codebases for privacy risks, generates DPIA documentation, tracks data subject rights requests with Art. 12(3) one-month deadlines. Use when running GDPR compliance assessments, privacy audits, data protection planning, DPIA generation, or data subject rights (DSAR) management (e.g., 'check this service for GDPR risks', 'track an access request deadline'). Final compliance determinations route to the DPO or legal counsel. --- # GDPR/DSGVO Expert @@ -75,7 +75,7 @@ python scripts/dpia_generator.py --input input.json --output dpia_report.md - Systematic monitoring (Art. 35(3)(c)) - Large-scale special category data (Art. 35(3)(b)) - Automated decision-making (Art. 35(3)(a)) -- WP29 high-risk criteria +- EDPB-endorsed high-risk criteria (WP248 rev.01) --- @@ -105,13 +105,13 @@ python scripts/data_subject_rights_tracker.py template --id DSR-202601-0001 | Right | Article | Deadline | |-------|---------|----------| -| Access | Art. 15 | 30 days | -| Rectification | Art. 16 | 30 days | -| Erasure | Art. 17 | 30 days | -| Restriction | Art. 18 | 30 days | -| Portability | Art. 20 | 30 days | -| Objection | Art. 21 | 30 days | -| Automated decisions | Art. 22 | 30 days | +| Access | Art. 15 | One month (Art. 12(3)) | +| Rectification | Art. 16 | One month (Art. 12(3)) | +| Erasure | Art. 17 | One month (Art. 12(3)) | +| Restriction | Art. 18 | One month (Art. 12(3)) | +| Portability | Art. 20 | One month (Art. 12(3)) | +| Objection | Art. 21 | One month (Art. 12(3)) | +| Automated decisions | Art. 22 | One month (Art. 12(3)) | **Features:** - Deadline tracking with overdue alerts @@ -150,7 +150,7 @@ German-specific requirements including: Step-by-step DPIA process: - Threshold assessment criteria -- WP29 high-risk indicators +- EDPB-endorsed high-risk indicators (WP248 rev.01) - Risk assessment methodology - Mitigation measure categories - DPO and supervisory authority consultation @@ -248,7 +248,7 @@ Requires explicit consent or Art. 9(2) exception: ### Data Subject Rights -All rights must be fulfilled within **30 days** (extendable to 90 for complex requests): +All rights must be fulfilled within **one month of receipt** (Art. 12(3)). The deadline runs by calendar month, not 30 days, and may be extended by **two further months** for complex or numerous requests — the data subject must be informed of the extension (with reasons) within the first month: - **Access**: Provide copy of data and processing information - **Rectification**: Correct inaccurate data - **Erasure**: Delete data (with exceptions for legal obligations) diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md b/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md index 5cd19df0..c176958d 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/references/gdpr_compliance_guide.md @@ -93,7 +93,7 @@ Additional safeguards required for: 1. Receive request (any form acceptable) 2. Verify identity (proportionate measures) 3. Gather data from all systems -4. Provide response within 30 days +4. Provide response within one month (Art. 12(3); extendable by two further months for complex requests) 5. First copy free; reasonable fee for additional ### Right to Rectification (Art. 16) @@ -106,7 +106,7 @@ Additional safeguards required for: 1. Verify claimed inaccuracy 2. Correct data in all systems 3. Notify third parties of correction -4. Respond within 30 days +4. Respond within one month (Art. 12(3)) ### Right to Erasure (Art. 17) diff --git a/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py b/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py index da9354b7..d0e6cde7 100644 --- a/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py +++ b/ra-qm-team/skills/gdpr-dsgvo-expert/scripts/data_subject_rights_tracker.py @@ -22,12 +22,30 @@ from typing import Dict, List, Optional from uuid import uuid4 +def add_months(dt: datetime, months: int) -> datetime: + """Add calendar months per GDPR Art. 12(3) (one month, not 30 days). + + If the target month has no equivalent day (e.g., Jan 31 + 1 month), + clamp to the last day of the target month. + """ + month_index = dt.month - 1 + months + year = dt.year + month_index // 12 + month = month_index % 12 + 1 + # last day of target month + if month == 12: + next_month_first = datetime(year + 1, 1, 1) + else: + next_month_first = datetime(year, month + 1, 1) + last_day = (next_month_first - timedelta(days=1)).day + return dt.replace(year=year, month=month, day=min(dt.day, last_day)) + + # GDPR Articles for each right RIGHTS_TYPES = { "access": { "article": "Art. 15", "name": "Right of Access", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to obtain confirmation of processing and access to their data", "response_includes": [ "Purposes of processing", @@ -42,7 +60,7 @@ RIGHTS_TYPES = { "rectification": { "article": "Art. 16", "name": "Right to Rectification", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to have inaccurate personal data corrected", "response_includes": [ "Confirmation of correction", @@ -53,7 +71,7 @@ RIGHTS_TYPES = { "erasure": { "article": "Art. 17", "name": "Right to Erasure (Right to be Forgotten)", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to have their personal data erased", "grounds": [ "Data no longer necessary for original purpose", @@ -74,7 +92,7 @@ RIGHTS_TYPES = { "restriction": { "article": "Art. 18", "name": "Right to Restriction of Processing", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to restrict processing of their data", "grounds": [ "Accuracy contested (during verification)", @@ -86,7 +104,7 @@ RIGHTS_TYPES = { "portability": { "article": "Art. 20", "name": "Right to Data Portability", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to receive their data in a portable format", "conditions": [ "Processing based on consent or contract", @@ -101,7 +119,7 @@ RIGHTS_TYPES = { "objection": { "article": "Art. 21", "name": "Right to Object", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right to object to processing", "applies_to": [ "Processing based on legitimate interests", @@ -112,7 +130,7 @@ RIGHTS_TYPES = { "automated": { "article": "Art. 22", "name": "Rights Related to Automated Decision-Making", - "deadline_days": 30, + "deadline_months": 1, # Art. 12(3): one month of receipt "description": "Data subject has the right not to be subject to solely automated decisions", "includes": [ "Right to human intervention", @@ -173,7 +191,8 @@ class RightsTracker: right_info = RIGHTS_TYPES[right_type] now = datetime.now() - deadline = now + timedelta(days=right_info["deadline_days"]) + # Art. 12(3): respond within one calendar month of receipt + deadline = add_months(now, right_info["deadline_months"]) request = { "id": self._generate_id(), @@ -223,9 +242,10 @@ class RightsTracker: elif new_status == "completed": req["dates"]["completed"] = datetime.now().isoformat() elif new_status == "extended": - # Extend deadline by additional 60 days (max total 90) + # Art. 12(3): extendable by two further calendar months for + # complex/numerous requests (data subject informed within month 1) original_deadline = datetime.fromisoformat(req["dates"]["deadline"]) - req["dates"]["deadline"] = (original_deadline + timedelta(days=60)).isoformat() + req["dates"]["deadline"] = add_months(original_deadline, 2).isoformat() if note: req["notes"].append({ @@ -531,7 +551,7 @@ def main(): for key, info in RIGHTS_TYPES.items(): print(f"\n{key} ({info['article']})") print(f" {info['name']}") - print(f" Deadline: {info['deadline_days']} days") + print(f" Deadline: {info['deadline_months']} calendar month(s) (Art. 12(3))") else: parser.print_help() diff --git a/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md b/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md index 77723e96..62102a4a 100644 --- a/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md +++ b/ra-qm-team/skills/information-security-manager-iso27001/SKILL.md @@ -1,6 +1,6 @@ --- name: "information-security-manager-iso27001" -description: ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use for ISMS design, security risk assessment, control implementation, ISO 27001 certification, security audits, incident response, and compliance verification. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity. +description: ISO 27001 ISMS implementation and cybersecurity governance for HealthTech and MedTech companies. Use when designing an ISMS, running security risk assessments, implementing controls, pursuing ISO 27001 certification, preparing security audits, responding to security incidents, or verifying compliance. Covers ISO 27001, ISO 27002, healthcare security, and medical device cybersecurity. --- # Information Security Manager - ISO 27001 diff --git a/ra-qm-team/skills/mdr-745-specialist/SKILL.md b/ra-qm-team/skills/mdr-745-specialist/SKILL.md index bc938801..8355cd26 100644 --- a/ra-qm-team/skills/mdr-745-specialist/SKILL.md +++ b/ra-qm-team/skills/mdr-745-specialist/SKILL.md @@ -1,6 +1,6 @@ --- name: "mdr-745-specialist" -description: EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, and EUDAMED integration. +description: EU MDR 2017/745 compliance specialist for medical device classification, technical documentation, clinical evidence, and post-market surveillance. Covers Annex VIII classification rules, Annex II/III technical files, Annex XIV clinical evaluation, Art. 86 PSUR schedules, and EUDAMED integration. Use when classifying a medical device under MDR, building or gap-checking a technical file, planning clinical evaluation or PMS/PSUR cadence, or preparing for notified body review (e.g., 'what class is my device under MDR', 'review my PSUR schedule'). triggers: - MDR compliance - EU MDR @@ -125,8 +125,8 @@ ANNEX II TECHNICAL DOCUMENTATION | I | Annex II self-declaration | None | | Is/Im | Annex II + IX/XI | Sterile/measuring aspects | | IIa | Annex II + IX or XI | Product or QMS | -| IIb | Annex IX + X or X + XI | Type exam + production | -| III | Annex IX + X | Full QMS + type exam | +| IIb | Annex IX, or Annex X + XI | QMS + tech doc assessment, or type exam + production | +| III | Annex IX, or Annex X + XI | Full QMS + product dossier, or type exam + production | --- @@ -193,19 +193,19 @@ Establish PMS system per Chapter VII: | Component | Requirement | Frequency | |-----------|-------------|-----------| | PMS Plan | Article 84 | Maintain current | -| PSUR | Class IIa and higher | Per class schedule | +| PSUR | Article 86 — Class IIa and higher | Per Art. 86(1) schedule below | | PMCF Plan | Annex XIV Part B | Update with CER | | PMCF Report | Annex XIV Part B | Annual (Class III) | | Vigilance | Articles 87-92 | As events occur | ### PSUR Schedule -| Class | Frequency | -|-------|-----------| -| Class III | Annual | -| Class IIb implantable | Annual | -| Class IIb | Every 2 years | -| Class IIa | When necessary | +| Class | Frequency (MDR Art. 86(1)) | +|-------|-----------------------------| +| Class III | Updated at least annually | +| Class IIb (all, incl. implantable) | Updated at least annually | +| Class IIa | When necessary, at least every 2 years | +| Class I | No PSUR — PMS report instead (Art. 85) | ### Serious Incident Reporting diff --git a/ra-qm-team/skills/qms-audit-expert/SKILL.md b/ra-qm-team/skills/qms-audit-expert/SKILL.md index 65941251..9705a0f4 100644 --- a/ra-qm-team/skills/qms-audit-expert/SKILL.md +++ b/ra-qm-team/skills/qms-audit-expert/SKILL.md @@ -1,6 +1,6 @@ --- name: "qms-audit-expert" -description: ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use for internal audit planning, audit execution, finding classification, external audit preparation, or audit program management. +description: ISO 13485 internal audit expertise for medical device QMS. Covers audit planning, execution, nonconformity classification, and CAPA verification. Use when planning internal audits, executing audits, classifying findings, preparing for external audits, or managing an audit program. triggers: - ISO 13485 audit - internal audit diff --git a/ra-qm-team/skills/quality-documentation-manager/SKILL.md b/ra-qm-team/skills/quality-documentation-manager/SKILL.md index c461077f..3581400c 100644 --- a/ra-qm-team/skills/quality-documentation-manager/SKILL.md +++ b/ra-qm-team/skills/quality-documentation-manager/SKILL.md @@ -1,6 +1,6 @@ --- name: "quality-documentation-manager" -description: Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use for document control procedures, change control workflow, document numbering, version management, electronic signature compliance, or regulatory documentation review. +description: Document control system management for medical device QMS. Covers document numbering, version control, change management, and 21 CFR Part 11 compliance. Use when working on document control procedures, change control workflows, document numbering, version management, electronic signature compliance, or regulatory documentation review. triggers: - document control - document numbering diff --git a/ra-qm-team/skills/quality-manager-qmr/SKILL.md b/ra-qm-team/skills/quality-manager-qmr/SKILL.md index 5758133d..dcbb834b 100644 --- a/ra-qm-team/skills/quality-manager-qmr/SKILL.md +++ b/ra-qm-team/skills/quality-manager-qmr/SKILL.md @@ -1,6 +1,6 @@ --- name: "quality-manager-qmr" -description: Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. +description: Senior Quality Manager Responsible Person (QMR) for HealthTech and MedTech companies. Provides quality system governance, management review leadership, regulatory compliance oversight, and quality performance monitoring per ISO 13485 Clause 5.5.2. Use when leading management reviews, setting quality policy and objectives, monitoring quality KPIs and cost of quality, or exercising QMR governance and regulatory oversight responsibilities. triggers: - management review - quality policy diff --git a/ra-qm-team/skills/ra-qm-skills/SKILL.md b/ra-qm-team/skills/ra-qm-skills/SKILL.md index d6342a2f..c88ddf7c 100644 --- a/ra-qm-team/skills/ra-qm-skills/SKILL.md +++ b/ra-qm-team/skills/ra-qm-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: "ra-qm-skills" -description: "12 regulatory & QM agent skills and plugins for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. ISO 13485 QMS, MDR 2017/745, FDA 510(k)/PMA, ISO 27001 ISMS, GDPR/DSGVO, risk management (ISO 14971), CAPA, document control, auditing. Python tools (stdlib-only)." +description: "Router/index for the 15 regulatory & quality-management skills bundled in this plugin (ISO 13485 QMS, EU MDR 2017/745, FDA submissions under QMSR, ISO 14971 risk, CAPA, document control, ISO 27001/ISMS, ISO 42001 AIMS, EU AI Act, GDPR/DSGVO, SOC 2, auditing). Use when a compliance request doesn't obviously match one skill and you need to pick the right one (e.g., 'prepare us for an ISO 13485 audit', 'is my AI system high-risk under the AI Act')." version: 2.9.0 author: Alireza Rezvani license: MIT @@ -18,49 +18,42 @@ agents: - openclaw --- -# Regulatory Affairs & Quality Management Skills +# Regulatory Affairs & Quality Management Skills — Router -12 production-ready compliance skills for HealthTech and MedTech organizations. +This plugin bundles **15 compliance skills** for HealthTech/MedTech organizations (this router is the 16th folder under `ra-qm-team/skills/`). Each skill is self-contained. -## Quick Start +## Routing table -### Claude Code -``` -/read ra-qm-team/skills/regulatory-affairs-head/SKILL.md -``` +Match the request, then load `ra-qm-team/skills//SKILL.md`. If multiple rows match, ask one clarifying question first. -### Codex CLI -```bash -npx agent-skills-cli add alirezarezvani/claude-skills/ra-qm-team -``` +| Request signals | Skill | Path | +|---|---|---| +| Regulatory strategy, pathway selection, submissions planning | regulatory-affairs-head | `skills/regulatory-affairs-head/` | +| Management review, quality KPIs, QMR governance | quality-manager-qmr | `skills/quality-manager-qmr/` | +| ISO 13485 QMS implementation, process control | quality-manager-qms-iso13485 | `skills/quality-manager-qms-iso13485/` | +| ISO 14971 risk analysis, FMEA, risk files | risk-management-specialist | `skills/risk-management-specialist/` | +| Root cause analysis, corrective/preventive actions | capa-officer | `skills/capa-officer/` | +| Document control, 21 CFR Part 11, DHF/DMR/DHR | quality-documentation-manager | `skills/quality-documentation-manager/` | +| ISO 13485 internal audits, NC classification | qms-audit-expert | `skills/qms-audit-expert/` | +| ISO 27001 audit planning and execution | isms-audit-expert | `skills/isms-audit-expert/` | +| ISMS design, security risk assessment | information-security-manager-iso27001 | `skills/information-security-manager-iso27001/` | +| EU MDR classification, technical files, PSUR | mdr-745-specialist | `skills/mdr-745-specialist/` | +| FDA 510(k)/PMA/De Novo, QMSR | fda-consultant-specialist | `skills/fda-consultant-specialist/` | +| GDPR/DSGVO, DPIA, data subject rights | gdpr-dsgvo-expert | `skills/gdpr-dsgvo-expert/` | +| EU AI Act risk classification, obligations | eu-ai-act-specialist | `skills/eu-ai-act-specialist/` | +| ISO/IEC 42001 AI management system | iso42001-specialist | `skills/iso42001-specialist/` | +| SOC 2 Type I/II readiness, trust criteria | soc2-compliance | `skills/soc2-compliance/` | -## Skills Overview - -| Skill | Folder | Focus | -|-------|--------|-------| -| Regulatory Affairs Head | `regulatory-affairs-head/` | FDA/MDR strategy, submissions | -| Quality Manager (QMR) | `quality-manager-qmr/` | QMS governance, management review | -| Quality Manager (ISO 13485) | `quality-manager-qms-iso13485/` | QMS implementation, doc control | -| Risk Management Specialist | `risk-management-specialist/` | ISO 14971, FMEA, risk files | -| CAPA Officer | `capa-officer/` | Root cause analysis, corrective actions | -| Quality Documentation Manager | `quality-documentation-manager/` | Document control, 21 CFR Part 11 | -| QMS Audit Expert | `qms-audit-expert/` | ISO 13485 internal audits | -| ISMS Audit Expert | `isms-audit-expert/` | ISO 27001 security audits | -| Information Security Manager | `information-security-manager-iso27001/` | ISMS implementation | -| MDR 745 Specialist | `mdr-745-specialist/` | EU MDR classification, CE marking | -| FDA Consultant | `fda-consultant-specialist/` | 510(k), PMA, QSR compliance | -| GDPR/DSGVO Expert | `gdpr-dsgvo-expert/` | Privacy compliance, DPIA | - -## Python Tools - -17 scripts, all stdlib-only: +## Quick start ```bash +# Example: route a risk-analysis request +cat ra-qm-team/skills/risk-management-specialist/SKILL.md python3 ra-qm-team/skills/risk-management-specialist/scripts/risk_matrix_calculator.py --help -python3 ra-qm-team/skills/gdpr-dsgvo-expert/scripts/gdpr_compliance_checker.py --help ``` ## Rules -- Load only the specific skill SKILL.md you need -- Always verify compliance outputs against current regulations +- Route to exactly one skill, then follow that skill's workflow. This router ships no tools of its own. +- All outputs are decision support: final compliance determinations route to the named human owner (QMR, DPO, regulatory counsel) — never auto-decide. +- Verify regulatory citations against the current text (e.g., FDA QMSR effective 2026-02-02 replaced the legacy QSR subsections). diff --git a/research/dossier/skills/dossier/SKILL.md b/research/dossier/skills/dossier/SKILL.md index f2d379e7..a5d5f6bb 100644 --- a/research/dossier/skills/dossier/SKILL.md +++ b/research/dossier/skills/dossier/SKILL.md @@ -1,6 +1,6 @@ --- name: dossier -description: "Decision-grade entity research skill — produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network signals, reputation signals, red flags, 3-5 conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica Nonprofit Explorer) as workhorses; optional BYOK MCPs (LinkedIn, Crunchbase, Apollo, Pitchbook, SimilarWeb) enhance coverage. Triggers: 'research [company]', 'dossier on [person/company]', 'background check on [entity]', 'prep me for a meeting with [person/company]', 'due diligence on [company]', 'what should I know about [entity]', 'research [person] before I [meet/hire/invest]', 'competitor research on [company]', 'investor diligence [company]', 'interview prep for [company]'. Honors sensitivity exclusions for journalism + personal-vetting contexts." +description: "Decision-grade entity research skill — produces a hypothesis-tested dossier on a specific company, person, nonprofit, or government org, not a generic profile. Forcing intake makes the user state their hypothesis upfront (what they already believe and want to verify or disprove) so the dossier tests it rather than confirms it. Output is an editable Word document (.docx) with verdict on the hypothesis, identity facts, 12-month activity timeline, network and reputation signals, red flags, conversation hooks tied to specific findings, and source-provenance audit log. Uses WebSearch + WebFetch + free APIs (SEC EDGAR, GitHub, ProPublica) as workhorses; optional BYOK MCPs enhance coverage. Use when the user asks for background research, diligence, or meeting prep on a specific entity (e.g., 'prep me for a meeting with [person/company]', 'due diligence on [company]'). Honors sensitivity exclusions for journalism + personal-vetting contexts." license: MIT metadata: source_spec: "megaprompts/12-dossier-megaprompt.md" diff --git a/research/grants/skills/grants/SKILL.md b/research/grants/skills/grants/SKILL.md index eded41ec..ee88f167 100644 --- a/research/grants/skills/grants/SKILL.md +++ b/research/grants/skills/grants/SKILL.md @@ -1,6 +1,6 @@ --- name: grants -description: "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommendation. Triggers: 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research', or any grant-related request. NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." +description: "NIH grant research skill for clinical researchers. Grill-me intake (research idea + career stage + preliminary data + environment + submission posture + known institute targets) locks down the funding strategy before any search runs. Runs a 5-facet Consensus positioning analysis (with draft Significance/Innovation language), maps the research to the right NIH institutes and study sections via RePORTER, finds NOSIs and funded overlap, and produces an editable Word document (.docx) with budget/scope-aware mechanism recommendations, submission timelines, and a mandatory program officer recommendation. Use when the user asks about research funding or makes any grant-related request (e.g., 'grants for [topic]', 'find grants for my research idea', 'what grants match my research', 'help me find NIH funding', 'grant opportunities for my research'). NIH-only scope — non-NIH funders (PCORI, DOD CDMRP, VA, foundations) are out of scope and flagged at intake." license: MIT metadata: source_spec: "megaprompts/08-grants-megaprompt.md" diff --git a/research/litreview/skills/litreview/SKILL.md b/research/litreview/skills/litreview/SKILL.md index f8ce4a69..9137a55e 100644 --- a/research/litreview/skills/litreview/SKILL.md +++ b/research/litreview/skills/litreview/SKILL.md @@ -1,6 +1,6 @@ --- name: litreview -description: "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a professionally formatted Word document (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — not a finished review, but an orientation guide that lets a researcher dive in confidently. Triggers: 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'. Do NOT trigger for single one-off paper searches where the user just wants a quick list — that's a plain Consensus search." +description: "Academic literature orientation skill that searches papers via Consensus, builds a strategic search plan using PICO (default) or SPIDER / Decomposition / hybrid as fallbacks, and synthesizes findings into a formatted Word (.docx) research guide. Grill-me intake (research question specificity + framework hint + tentative depth) before the recon search; a second forcing checkpoint after Phase 2 confirms framework + sub-areas + depth before searches consume budget. Configurable depth (5/10/20 queries) controls coverage vs. speed. Output is a 'launching pad' — an orientation guide that lets a researcher dive in confidently, not a finished review. Use when the user starts literature-oriented research (e.g., 'litreview on [topic]', 'literature review on [topic]', 'I'm starting a literature review on X', 'I'm writing a paper on X', 'help me research X', 'I'm doing research on X', 'can you help me research X'). Do NOT use for single one-off paper searches wanting a quick list — that's a plain Consensus search." license: MIT metadata: source_spec: "megaprompts/09-litreview-megaprompt.md" diff --git a/research/notebooklm/.claude-plugin/plugin.json b/research/notebooklm/.claude-plugin/plugin.json index da1b9ed8..61316339 100644 --- a/research/notebooklm/.claude-plugin/plugin.json +++ b/research/notebooklm/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "notebooklm", - "description": "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM \u2014 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment \u2014 fails gracefully when unavailable.", + "description": "Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable.", "version": "2.9.0", "author": { "name": "Alireza Rezvani", @@ -14,7 +14,7 @@ ], "source": { "spec": "megaprompts/03-notebooklm-megaprompt.md", - "build_pattern": "Path B (direct conversion). Browser-automation shape \u2014 distinct from research-pack convention. Action-routing intake (Q1 picks one of 4 actions: read/extract, add source, generate studio output, create new). CLI-only portability with graceful failure in web context.", + "build_pattern": "Path B (direct conversion). Browser-automation shape — distinct from research-pack convention. Action-routing intake (Q1 picks one of 4 actions: read/extract, add source, generate studio output, create new). CLI-only portability with graceful failure in web context.", "sibling_of": "research/pulse, litreview, grants, dossier, patent, syllabus (semantic domain) but DIFFERENT SHAPE (browser-automation, not research-pack)" } -} +} \ No newline at end of file diff --git a/research/notebooklm/skills/notebooklm/SKILL.md b/research/notebooklm/skills/notebooklm/SKILL.md index dd099bd0..57a10d8d 100644 --- a/research/notebooklm/skills/notebooklm/SKILL.md +++ b/research/notebooklm/skills/notebooklm/SKILL.md @@ -1,6 +1,6 @@ --- name: notebooklm -description: "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM — 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment — fails gracefully when unavailable." +description: "Browser automation skill for controlling Google's NotebookLM. Use when the user wants anything done in NotebookLM (e.g., 'open NotebookLM', 'check my [name] notebook', 'ask my notebook about X', 'add [source] to NotebookLM', 'generate a Video Overview from my notebook', 'use NotebookLM Studio'). Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio/Video Overviews, Mind Maps, Reports incl. Briefing Doc/Study Guide/FAQ, Flashcards, Quiz, slide decks, infographics — discover the exact set from the live Studio panel; the UI evolves fast), and creating new notebooks. Requires browser automation environment — fails gracefully when unavailable." license: MIT metadata: source_spec: "megaprompts/03-notebooklm-megaprompt.md" @@ -34,7 +34,7 @@ Up to 4 forcing questions, one at a time, dependency-ordered. Most invocations s > > 1. **Read / extract** — ask a question of an existing notebook > 2. **Add a source** — push content (URL, text, file, Google Doc, or synthesized content) into a notebook -> 3. **Generate a Studio output** — Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Infographic, Slides, or Mind Map +> 3. **Generate a Studio output** — Audio/Video Overview, Mind Map, Report (Briefing Doc, Study Guide, FAQ, Timeline), Flashcards, Quiz, Infographic, or Slides — the exact set comes from the live Studio panel > 4. **Create a new notebook** — initialize with title + initial sources > > *Why I'm asking:* Each action takes a different path through the UI and requires different parameters. Naming the action upfront prevents wasted screenshots and lets me ask only the follow-up questions that apply. @@ -65,7 +65,7 @@ For action 4 (create new): replace with "What's the title for the new notebook?" > *Why I'm asking:* Each source type goes through a different sub-flow in the Add Source dialog. Picking upfront saves a step." **Action 3 (Studio output):** -> "Which Studio output? Audio Overview / Study Guide / Briefing Doc / Timeline / FAQ / Table of Contents / Infographic / Slides / Mind Map. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. +> "Which Studio output? As of 2026-06 the Studio panel offers Audio Overview, Video Overview, Mind Map, Reports (Briefing Doc / Study Guide / FAQ / Timeline / custom), Flashcards, Quiz, Infographic, and Slides — I'll screenshot the live panel and confirm what your account actually shows before clicking. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience. > > *Why I'm asking:* The output type sets the UI button to find. The custom prompt is mandatory for quality." @@ -132,12 +132,12 @@ Sub-flows per source type: ## Action 3: Studio Outputs -**All 9 output types supported:** Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Table of Contents, Infographic, Slides, Mind Map. +**Discover, don't assume.** NotebookLM's Studio inventory changes between rollouts and account tiers. As of the last verification (2026-06) the panel offers: **Audio Overview, Video Overview, Mind Map, Reports** (Briefing Doc, Study Guide, FAQ, Timeline, custom report formats), **Flashcards, Quiz, Infographic, Slides**. Treat this list as a hint, not ground truth — the screenshot of the live Studio panel is the authority. NotebookLM's UI evolves quickly; verify against the live product and update this section when it drifts (Studio inventory last verified 2026-06). **Mandatory workflow:** -1. Locate Studio panel (right side; may need toggle) -2. Find the specific output button for the requested type +1. Locate Studio panel (right side; may need toggle) and **screenshot it — the tiles you see are the real output types for this account** +2. Find the specific output button for the requested type (if it isn't visible, check "Discover more"/overflow before declaring it unavailable) 3. **Open customization menu** (chevron/arrow next to button) — **NOT the main button** 4. **Write detailed custom prompt** (from Q4) 5. Confirm and submit @@ -183,10 +183,18 @@ Use `scripts/async_action_classifier.py` to determine wait-or-notify per action: | Add Source (URL/text/file) | Yes — wait for ingestion spinner (~5-30s) | | Read/Extract (chat) | Yes — wait 3-5s for response | | Studio: Audio Overview | **No** — fire and notify (5-10 min) | +| Studio: Video Overview | **No** — fire and notify (5-15 min) | | Studio: Infographic / Slides / Mind Map | **No** — fire and notify (2-5 min) | -| Studio: Study Guide / Briefing Doc / FAQ | Yes — wait ~30-60s | +| Studio: Study Guide / Briefing Doc / FAQ / Flashcards / Quiz | Yes — wait ~30-60s | | Create New Notebook | Yes — wait for auto-summary (<30s) | +```bash +# Verdict + paste-ready notify message for any action +python3 scripts/async_action_classifier.py --action "video overview" +# -> Verdict: FIRE_AND_NOTIFY, estimated 5-15 minutes, with the exact +# "NOT waiting in this session" message to relay to the user +``` + See [`references/async_action_discipline.md`](references/async_action_discipline.md) for the canon. ## Screenshot-First Discipline diff --git a/research/notebooklm/skills/notebooklm/references/async_action_discipline.md b/research/notebooklm/skills/notebooklm/references/async_action_discipline.md index 0fc9be89..44d1024c 100644 --- a/research/notebooklm/skills/notebooklm/references/async_action_discipline.md +++ b/research/notebooklm/skills/notebooklm/references/async_action_discipline.md @@ -47,7 +47,8 @@ The user already knows how NotebookLM works — they'll see the notification whe | Studio: Study Guide | Generation | 30-60s | **Wait** (with 90s timeout) | | Studio: Briefing Doc | Generation | 30-60s | **Wait** (with 90s timeout) | | Studio: FAQ | Generation | 30-60s | **Wait** (with 90s timeout) | -| Studio: Table of Contents | Generation | 20-40s | **Wait** | +| Studio: Flashcards / Quiz | Generation | 30-60s | **Wait** | +| Studio: Video Overview | Generation | 5-15 min | **Fire-and-notify** | | Studio: Timeline | Generation | 30-60s | **Wait** (with 90s timeout) | | **Studio: Audio Overview** | Audio gen | **5-10 min** | **NOTIFY** (fire-and-notify) | | **Studio: Infographic** | Visual gen | **2-5 min** | **NOTIFY** | diff --git a/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md b/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md index bd1893e8..163d8f2d 100644 --- a/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md +++ b/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md @@ -4,17 +4,18 @@ This reference answers exactly one decision: **why does the notebooklm skill alw ## The Core Claim -NotebookLM's Studio generates 9 output types from your notebook's sources: +NotebookLM's Studio generates multiple output types from your notebook's sources. As of the last verification (2026-06): - Audio Overview (podcast-style) -- Study Guide -- Briefing Doc -- Timeline -- FAQ -- Table of Contents +- Video Overview (narrated visual explainer; customizable format and visual style) +- Mind Map +- Reports — Briefing Doc, Study Guide, FAQ, Timeline, and custom report formats +- Flashcards +- Quiz - Infographic - Slides (slide deck) -- Mind Map + +The UI evolves quickly — always discover the actual inventory from the live Studio panel screenshot rather than this list, and update this doc when it drifts. **The default prompts produce mediocre output.** They are written to work across all possible source materials → they are generic by design. Generic prompts produce generic output. @@ -150,7 +151,7 @@ A weak prompt has 1-2 of these. A strong prompt has 4-5. > "Central concept: [name]. 3-5 primary branches (the major dimensions). Each branch: 2-4 sub-branches. Max depth: 3 levels (central → branch → sub-branch). Use noun phrases for branches (not full sentences). Mark 2-3 sub-branches as 'critical' (the highest-leverage points). Skip details that don't connect back to a critical sub-branch." -### Table of Contents +### Table of Contents (legacy — folded into Reports in current UI) **Default fails because:** literal section dump, no annotation. diff --git a/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py b/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py index 9ce4056a..7903052c 100644 --- a/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py +++ b/research/notebooklm/skills/notebooklm/scripts/async_action_classifier.py @@ -114,7 +114,32 @@ ACTION_TIMING = { "timeout_seconds": 90, "polling_interval_seconds": 5, }, + "flashcards": { + "category": "studio", + "verdict": "WAIT", + "estimated_duration_seconds": (30, 60), + "timeout_seconds": 120, + "polling_interval_seconds": 10, + }, + "quiz": { + "category": "studio", + "verdict": "WAIT", + "estimated_duration_seconds": (30, 60), + "timeout_seconds": 120, + "polling_interval_seconds": 10, + }, # Studio outputs — slow (fire-and-notify) + "video_overview": { + "category": "studio", + "verdict": "FIRE_AND_NOTIFY", + "estimated_duration_seconds": (300, 900), + "estimated_duration_human": "5-15 minutes", + "notify_message": ( + "Video Overview generation triggered. Estimated 5-15 minutes. " + "NotebookLM will notify you in-app and via email when ready. " + "NOT waiting in this session — returning control to you now." + ), + }, "audio_overview": { "category": "studio", "verdict": "FIRE_AND_NOTIFY", diff --git a/research/patent/skills/patent/SKILL.md b/research/patent/skills/patent/SKILL.md index 4f412a16..dcc7cb99 100644 --- a/research/patent/skills/patent/SKILL.md +++ b/research/patent/skills/patent/SKILL.md @@ -1,6 +1,6 @@ --- name: patent -description: "Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Triggers: 'prior art search for [invention]', 'patent search on [topic]', 'freedom to operate analysis', 'FTO for [product]', 'patent landscape for [field]', 'is [invention] novel', 'patents on [topic]', 'competitive patent analysis', 'prior art for litigation', 'patent diligence on [company]'. Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." +description: "Patent prior-art and landscape intelligence skill — not generic patent help. Commits to one of five sub-use-cases via forcing intake (novelty search / freedom-to-operate / competitive landscape / acquisition diligence / litigation prior-art) before any search runs. Searches Google Patents, Espacenet, USPTO, and optionally Lens.org for citation-graph signals. Output is an editable Word document (.docx) with verdict, ranked closest art (claim-text extracted), CPC-class-aware landscape, family-resolved hits, geographic coverage, FTO flags where applicable, strategy recommendations, and full audit log. Use when the user asks for patent searching or analysis (e.g., 'prior art search for [invention]', 'freedom to operate analysis for [product]'). Produces search signal, not legal advice — always recommends consulting a patent attorney before filing or licensing decisions. Trademark, copyright, and trade-secret questions are out of scope." license: MIT metadata: source_spec: "megaprompts/11-patent-megaprompt.md" diff --git a/research/pulse/skills/pulse/SKILL.md b/research/pulse/skills/pulse/SKILL.md index c79d48a1..31319172 100644 --- a/research/pulse/skills/pulse/SKILL.md +++ b/research/pulse/skills/pulse/SKILL.md @@ -1,6 +1,6 @@ --- name: pulse -description: "Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Triggers: 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]', or any variation requesting multi-source recency intelligence on a topic. Also use for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." +description: "Multi-source recency research skill that takes the pulse of any topic across Reddit, Hacker News, the open web, and optionally X/Twitter within a configurable recent window (default 30 days). Forcing intake clarifies topic specificity, angle (trend/sentiment/problems/opportunities/comparison), time window, and platform scope before searching. Returns a synthesized briefing with citations, engagement metrics, and cross-platform pattern analysis. Use when the user requests multi-source recency intelligence on a topic (e.g., 'pulse on [topic]', 'what's happening with [topic]', 'what are people saying about [topic]', 'current conversation about [topic]', 'take the pulse of [topic]', 'trending: [topic]', 'find me info on [topic]'), and for competitor research, trend discovery, tool comparisons, and audience sentiment analysis." license: MIT metadata: source_spec: "megaprompts/01-pulse-megaprompt.md" diff --git a/research/research/skills/research/SKILL.md b/research/research/skills/research/SKILL.md index f521084f..b899a52f 100644 --- a/research/research/skills/research/SKILL.md +++ b/research/research/skills/research/SKILL.md @@ -1,6 +1,6 @@ --- name: research -description: Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Triggers — "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]", or any research request that doesn't obviously match a more-specific specialist skill. Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log. +description: Default entry point for any research request — a hybrid router that classifies the question deterministically and either delegates to a specialist research skill (pulse for trends/sentiment, grants for NIH funding, litreview for academic literature, syllabus for course reading, patent for prior-art + IP landscape, dossier for entity research) or runs its own plan-decompose-multi-source-search-synthesize-cite fallback workflow when no specialist matches. Always surfaces the routing decision so users can override. Use when the user makes any research request that doesn't obviously match a more-specific specialist skill (e.g., "research [topic]", "look into [topic]", "what do we know about [topic]", "investigate [topic]", "find me information on [topic]", "do some research on [topic]", "I need to understand [topic]"). Output is a markdown briefing (default) or .docx document (on request) with full citations and an audit log. --- # Research — Hybrid Router + Fallback diff --git a/research/syllabus/skills/syllabus/SKILL.md b/research/syllabus/skills/syllabus/SKILL.md index 42749a6d..1543e7b2 100644 --- a/research/syllabus/skills/syllabus/SKILL.md +++ b/research/syllabus/skills/syllabus/SKILL.md @@ -1,6 +1,6 @@ --- name: syllabus -description: "Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Triggers whenever a user uploads a syllabus, course outline, or curriculum document and wants supplementary readings. Also triggers on: 'syllabus reading list', 'find papers for my course', 'create a reading list from this syllabus', 'recent research for my class', 'supplementary readings', 'find journal articles for these topics', 'what recent papers cover this material', 'any new research on these course topics', 'update my syllabus with recent papers'. Even casual mentions when a syllabus is attached should trigger this skill." +description: "Generates a curated supplementary reading list from any course syllabus using Consensus academic search. Grill-me intake (syllabus input format + course audience + year range) plus a grouping forcing-options checkpoint before any search runs — so the reading list matches the course's level and recency need. Parses the syllabus to extract topics and learning outcomes, searches Consensus for recent peer-reviewed papers per topic, and produces a professionally formatted .docx with clickable Consensus links, plain-language summaries calibrated to audience level, and Bloom-higher-order discussion questions tied to course learning goals. Use when the user uploads a syllabus, course outline, or curriculum document and wants supplementary readings (e.g., 'create a reading list from this syllabus', 'find recent papers for my course') — even casual mentions with a syllabus attached should trigger this skill." license: MIT metadata: source_spec: "megaprompts/10-syllabus-megaprompt.md"