From adac283b890344723fd78869191115765a100eaf Mon Sep 17 00:00:00 2001 From: Ghita Filali <18337313+ghitafilali@users.noreply.github.com> Date: Sun, 31 May 2026 03:30:31 +0200 Subject: [PATCH] Clarify COE skill library fit --- SKILL.md | 1 + SKILL.md.tmpl | 1 + coe/SKILL.md | 40 ++++++++++++++++++++++------------------ coe/SKILL.md.tmpl | 40 ++++++++++++++++++++++------------------ 4 files changed, 46 insertions(+), 36 deletions(-) diff --git a/SKILL.md b/SKILL.md index 4269f6f4d..5fe1f5ca9 100644 --- a/SKILL.md +++ b/SKILL.md @@ -442,6 +442,7 @@ quality gates that produce better results than answering inline. - User asks to review design of a plan → invoke `/plan-design-review` - User asks about developer experience of a plan, API/CLI/SDK design → invoke `/plan-devex-review` - User wants all reviews done automatically, "review everything" → invoke `/autoplan` +- User asks for a COE, Correction of Error, postmortem, "why did this recur", "what was missed", or "do not let this happen again" → invoke `/coe` - User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke `/investigate` - User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke `/qa` - User asks to just report bugs without fixing → invoke `/qa-only` diff --git a/SKILL.md.tmpl b/SKILL.md.tmpl index a248cbfa3..e5b5104ce 100644 --- a/SKILL.md.tmpl +++ b/SKILL.md.tmpl @@ -38,6 +38,7 @@ quality gates that produce better results than answering inline. - User asks to review design of a plan → invoke `/plan-design-review` - User asks about developer experience of a plan, API/CLI/SDK design → invoke `/plan-devex-review` - User wants all reviews done automatically, "review everything" → invoke `/autoplan` +- User asks for a COE, Correction of Error, postmortem, "why did this recur", "what was missed", or "do not let this happen again" → invoke `/coe` - User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke `/investigate` - User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke `/qa` - User asks to just report bugs without fixing → invoke `/qa-only` diff --git a/coe/SKILL.md b/coe/SKILL.md index 501bc9b71..b3b161bb2 100644 --- a/coe/SKILL.md +++ b/coe/SKILL.md @@ -8,7 +8,8 @@ description: | evidence-backed COE reports with impact, timeline, 5+ Whys, corrective actions, and verification gates. Use when asked for "COE", "correction of error", "postmortem", "why did this recur", or "do not let this happen - again". (gstack) + again". Route active debugging to /investigate and pre-landing diff checks to + /review. (gstack) allowed-tools: - Bash - Read @@ -23,7 +24,6 @@ triggers: - postmortem - why did this recur - don't let this happen again - - root cause analysis --- @@ -678,6 +678,22 @@ The goal is not blame. The goal is to find the mechanism that let the failure happen, fix that mechanism, and prove the same class of failure is harder to repeat. +## Skill-library fit + +Use `/coe` for a formal post-failure Correction of Error: a recurring failure, +false success, missed work, data loss, brittle automation, or user-visible miss +that needs a written record with impact, timeline, root cause, corrective +actions, and verification. + +Adjacent GStack skills keep their narrower jobs: + +- `/investigate`: active debugging before the failure mechanism is understood. +- `/review`: pre-landing diff or PR risk review. +- `/retro`: engineering trends over a time window. +- `/skillify`: turning a proven workflow or corrective action into a durable + skill, script, test, or guardrail. +- `/health`: codebase health and quality dashboards. + ## Contract - Do not stop at symptom labels like "timeout", "LLM failed", "human error", @@ -697,21 +713,9 @@ repeat. it until it can be. - Finish with a verification gate and a clear residual-risk statement. -## Structure principles - -- DRY: put each fact in one place. Evidence belongs in Evidence, sequence in - Timeline, mechanism in Root Cause, fixes in Corrective Actions, and proof in - Verification. Cross-reference instead of repeating. -- MECE: classify on separate axes. Pick exactly one primary failure surface, - then add cause tags only when evidence supports them. -- If two categories overlap, rewrite them before reporting. If a category does - not cover the case, add an explicit "other/unknown" with the missing evidence. - ## Phase 1 - Failure classification -Classify on two separate axes. - -Primary failure surface: pick exactly one. +Classify the failure before changing anything. Name the primary failure mode: - Required work failed visibly: command, job, test, or pipeline failed and the required work did not complete. @@ -724,7 +728,7 @@ Primary failure surface: pick exactly one. - Optional diagnostic failed only: a non-required search, probe, or log lookup failed while required work is independently verified. -Cause tags: add one or more only after evidence. +Then identify evidence-backed contributing conditions: - timeout, rate limit, or transient provider failure - missing file, schema drift, or dependency drift @@ -849,8 +853,8 @@ One short paragraph: what failed, why it mattered, and what changed. -