diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a98bc03..0bbbc27 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -482,6 +482,15 @@ "strict": false, "description": "Build and maintain web frontends — component architecture, state management, API integration, responsive layout, client-side performance, and frontend testing patterns. Framework agnostic, focused on web frontend implementation. Do not use for backend service implementation, data engineering, or platform infrastructure work." }, + { + "name": "gap-analysis", + "source": "./", + "skills": [ + "./gap-analysis" + ], + "strict": false, + "description": "Analyze gaps by comparing a defined current state with a justified target state, characterizing causes and uncertainty, prioritizing actionable interventions, and producing traceable matrices, roadmaps, and decision records. Use for capability, process, compliance, readiness, maturity, operating-model, or research-evidence gaps. Do not use for a vague list of problems, a standalone root-cause analysis, a generic SWOT, or legal or audit certification advice without a governing standard and qualified owner." + }, { "name": "genius-life", "source": "./", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index a33cbc9..b33905c 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -71,6 +71,7 @@ "./forgejo-cli", "./forward-deployed-engineering", "./frontend-engineering", + "./gap-analysis", "./genius-life", "./ghost", "./github-runner", diff --git a/README.md b/README.md index 33ba109..445908c 100644 --- a/README.md +++ b/README.md @@ -221,6 +221,10 @@ Carry an embedded technical engagement from an ambiguous need to an adopted, mea Build and maintain web frontends — component architecture, state management, API integration, responsive layout, client-side performance, and frontend testing patterns. Framework agnostic, focused on web frontend implementation. Do not use for backend service implementation, data engineering, or platform infrastructure work. +### [gap-analysis](gap-analysis/SKILL.md) + +Conduct evidence-based gap analyses that compare a defined current state with a justified target state, characterize uncertainty and causes, prioritize action, and produce traceable registers, roadmaps, and decision records. + ### [genius-life](genius-life/SKILL.md) Guide a person in cultivating creativity in their own work and life: open conversational sessions on creative blocks, habits, environment, motivation, and resilience, or structured development of a concrete project or fledgling idea through a five-phase practice. Do not use for therapy or clinical support, general life coaching, product or stakeholder discovery, or as a study guide for a book. diff --git a/gap-analysis/README.md b/gap-analysis/README.md new file mode 100644 index 0000000..d9f2a04 --- /dev/null +++ b/gap-analysis/README.md @@ -0,0 +1,39 @@ +# gap-analysis + +Evidence-based comparison of a current state with a justified target state, producing actionable and reviewable decisions. + +## Why Install This Skill + +A gap analysis is easy to make look rigorous: add a current column, a target column, and a red/amber/green score. This skill teaches the harder part: defining a target that is actually warranted, collecting evidence that matches the question, separating observations from causes, and making trade-offs and uncertainty visible. + +After installing it, an agent can produce gap registers, capability and maturity assessments, process and operating-model reviews, compliance/readiness assessments, and research-evidence gap analyses. The included templates are designed to be adapted, not treated as a universal scoring system. + +## What You Get + +| Path | What it provides | +|---|---| +| `SKILL.md` | Method, routing, quality gates, and completion boundary | +| `references/` | Research-grounded methodology, variants, prioritization, examples, and source index | +| `templates/` | Gap register plus capability, process, compliance/readiness, and research variants | +| `scripts/validate-register.py` | Dependency-free checker for a JSON gap register | +| `evals/evals.json` | Output-quality cases for evidence, ambiguity, prioritization, and variants | + +## Quick Start + +No installation or API key is required. Read `SKILL.md`, choose a context template, and keep current evidence, target authority, confidence, owner, and closure test visible for every material gap. + +For a machine-checkable register: + +```sh +python3 gap-analysis/scripts/validate-register.py path/to/register.json +``` + +## Triggers + +Load this skill when you need to compare current and desired states for a capability, process, control, readiness decision, maturity question, operating model, or research evidence base. + +## Requirements + +- No external dependencies for the methodology or templates. +- Python 3 for the optional validator script. +- A defined decision, outcome, requirement, benchmark, or stakeholder target. Without one, the first deliverable is scoping, not a completed gap analysis. diff --git a/gap-analysis/SKILL.md b/gap-analysis/SKILL.md new file mode 100644 index 0000000..b6ce744 --- /dev/null +++ b/gap-analysis/SKILL.md @@ -0,0 +1,73 @@ +--- +name: gap-analysis +description: >- + Analyze gaps by comparing a defined current state with a justified target + state, characterizing causes and uncertainty, prioritizing actionable + interventions, and producing traceable matrices, roadmaps, and decision + records. Use for capability, process, compliance, readiness, maturity, + operating-model, or research-evidence gaps. Do not use for a vague list of + problems, a standalone root-cause analysis, a generic SWOT, or legal or + audit certification advice without a governing standard and qualified owner. +license: MIT +compatibility: Platform-agnostic methodology. No runtime dependency; optional Python 3 script uses only the standard library. +metadata: + tags: gap-analysis, current-state, target-state, capability, maturity, readiness, compliance, evidence, prioritization +--- + +# Gap Analysis + +## Overview + +A gap analysis is a decision method, not a scorecard: define a bounded question, establish an observable current state, justify a desired state, compare them, explain why the difference exists, and decide what to do. A credible result makes evidence, assumptions, uncertainty, ownership, and trade-offs visible. + +## When to use + +Load this skill when the work compares current and desired performance, capability, controls, process behavior, readiness, maturity, operating model, or research evidence and must produce an actionable artifact. Choose the variant from `references/variants.md`. + +### When not to use + +Do not use this as a substitute for root-cause analysis, a risk assessment, SWOT, benchmarking, a requirements specification, a regulatory/legal opinion, or an audit/certification conclusion. Route technical capacity questions to `capacity-and-cost-engineering`, governance questions to `ai-governance`, and causal diagnosis to `systematic-debugging` or the relevant domain owner. A gap analysis may expose a need for those disciplines; it does not replace them. + +## Core method + +1. **Frame the decision.** State the decision or outcome, sponsor, population/system, time horizon, boundary, exclusions, and who will use the result. +2. **Define the criterion.** Make the target observable and source it to a requirement, outcome, benchmark, risk appetite, strategy, or explicitly labeled stakeholder preference. Do not invent a maturity scale or imply that a framework tier is a universal goal. +3. **Specify evidence.** For each dimension, define measure, unit, period, source, sampling, confidence, and acceptance rule before collecting data. Separate observed facts, reported perceptions, inferred causes, and assumptions. +4. **Describe the current state.** Use multiple relevant evidence types: records/metrics, direct observation, interviews, artifacts, tests, or research synthesis. Record missing and contradictory evidence instead of filling it with confidence. +5. **Compare like with like.** For every dimension, show current, target, difference, evidence, confidence, and consequence. A gap is a bounded difference, not merely a bad feeling or an absence of a preferred practice. +6. **Characterize the gap.** Distinguish outcome gap, capability/control gap, process gap, resource gap, knowledge/evidence gap, and decision/ownership gap. Keep root causes and proposed remedies separate from the observed gap. +7. **Prioritize transparently.** Use criteria appropriate to the decision, such as impact, urgency/exposure, reach, feasibility, dependency, cost, confidence, and reversibility. Show the rationale and do not hide value judgments inside a score. +8. **Plan closure.** Convert selected gaps into actions with a measurable closure condition, owner, dependencies, resources, date or review trigger, and residual risk. Assign an accountable decision-maker, not “the team.” +9. **Validate and revisit.** Review findings with affected stakeholders, test high-consequence claims, resolve material contradictions, and schedule a follow-up measurement. Closure means evidence that the target condition is met, not that an action was started. + +## Required output shape + +Use `templates/gap-register.md` as the canonical row schema, then add only the context artifact needed: + +| Context | Add | +|---|---| +| Capability or maturity | `templates/capability-assessment.md` | +| Process or operating model | `templates/process-gap-analysis.md` | +| Compliance or readiness | `templates/compliance-readiness-assessment.md` | +| Research or evidence | `templates/research-evidence-gap.md` | + +A useful report normally contains: executive decision, scope and method, target/criteria register, current-state evidence, gap register, prioritization logic, action roadmap, assumptions/unknowns, stakeholder review, and follow-up measure. Label hypothetical examples as hypothetical. + +## Quality gates + +Before delivery, verify that each material gap has (a) a defined target and source, (b) current evidence or an explicit evidence gap, (c) a stated comparison and consequence, (d) a cause hypothesis distinguished from fact, (e) an owner and closure test, and (f) a priority rationale. Check that the report does not claim compliance, readiness, causation, or improvement without the evidence needed to support that claim. + +## Reference routing + +| Load this file when... | Reference | +|---|---| +| You need the research-grounded method, evidence taxonomy, or source limits | `references/methodology.md` | +| You need to choose among capability, process, compliance, readiness, maturity, or research variants | `references/variants.md` | +| You need prioritization, scoring, sequencing, or closure controls | `references/prioritization-and-roadmaps.md` | +| You need examples, anti-patterns, or review questions | `references/examples-and-anti-patterns.md` | +| You need source provenance and claims behind this skill | `references/source-index.md` | +| You need a structured checker for a completed JSON register | `scripts/validate-register.py` | + +## Completion + +Stop when the decision question is answered by a reviewed, traceable artifact, or report the bounded unresolved evidence and the next collection action. Do not convert missing data into a green score or keep researching after the decision-relevant uncertainty is explicit. diff --git a/gap-analysis/evals/evals.json b/gap-analysis/evals/evals.json new file mode 100644 index 0000000..3149430 --- /dev/null +++ b/gap-analysis/evals/evals.json @@ -0,0 +1,83 @@ +{ + "schema_version": 1, + "skill_name": "gap-analysis", + "evals": [ + { + "id": "bounded-operational-gap", + "prompt": "Our incident team restored a payment service in 75 and 110 minutes during two exercises. The recovery objective is 60 minutes. The runbook has no tested dependency fallback. Produce a gap analysis and next actions.", + "expected_output": "A bounded gap analysis that compares the measured recovery times with the stated objective, identifies the untested fallback as a capability/control gap or cause hypothesis rather than assuming training is the cause, states evidence and confidence, names an owner, and defines a closure test using representative exercises.", + "assertions": [ + "compares current recovery evidence with the 60-minute target", + "distinguishes the observed outcome gap from a cause hypothesis", + "identifies the untested dependency fallback as a control or capability issue", + "names an owner and a measurable closure test", + "does not claim that training is the proven cause" + ], + "case_set": "release" + }, + { + "id": "unsupported-target", + "prompt": "Assess whether our support organization is mature enough. We have no agreed maturity model, baseline metrics, or target state. Give us a scored gap analysis immediately.", + "expected_output": "The response refuses false precision, explains that the target and evidence protocol must be defined first, proposes a bounded scoping and target-setting step, and offers an unscored discovery artifact rather than inventing a maturity score.", + "assertions": [ + "does not invent a maturity scale or numeric score", + "states that target authority and baseline evidence are missing", + "proposes a scoping and target-definition step", + "labels any illustrative dimensions as provisional" + ], + "case_set": "regression" + }, + { + "id": "readiness-evidence-boundary", + "prompt": "Our launch checklist says security complete because a design review was approved, but no production-boundary test has run. Decide whether we are ready and create the gap artifact.", + "expected_output": "A readiness assessment that marks the control as implemented but unproven or unknown at the production boundary, identifies the missing test and acceptance criteria, names the decision authority, and avoids declaring readiness or compliance from the design review alone.", + "assertions": [ + "distinguishes design approval from production-boundary evidence", + "does not mark readiness as met solely from the design review", + "defines a boundary test and acceptance evidence", + "names an acceptance authority and residual risk", + "avoids a legal or certification conclusion" + ], + "case_set": "release" + }, + { + "id": "research-gap-classification", + "prompt": "A review finds inconsistent estimates, and its studies exclude the population affected by our decision. Identify the research gap and propose what evidence is needed next.", + "expected_output": "A research-evidence gap that identifies inconsistent/unknown results and not-the-right-information as reasons, explains the decision consequence, defines the relevant population and design needed, and avoids the empty recommendation to do more research.", + "assertions": [ + "classifies inconsistency as a reason the evidence falls short", + "classifies population mismatch as not-the-right-information", + "connects the gap to a decision consequence", + "specifies the population and evidence design needed next", + "does not treat more research as a sufficient action by itself" + ], + "case_set": "dev" + }, + { + "id": "prioritization-tradeoff", + "prompt": "We have three gaps: a high-impact but low-confidence control concern, a medium-impact well-evidenced process delay, and a low-impact easy documentation fix. Prioritize them and propose a roadmap.", + "expected_output": "A transparent prioritization that separates impact from confidence, sends the high-impact low-confidence item through urgent validation or a precautionary control as appropriate, sequences the process fix and documentation fix with rationale, and names owners and closure tests.", + "assertions": [ + "does not rank by gap size or ease alone", + "keeps confidence visible rather than hiding it in impact", + "proposes validation or precaution for the high-impact low-confidence concern", + "gives sequencing rationale for all three gaps", + "includes owners and closure tests" + ], + "case_set": "regression" + }, + { + "id": "variant-routing", + "prompt": "Compare an operating process to a new compliance requirement, assess team capability, and decide launch readiness in one report. What should the gap analysis contain?", + "expected_output": "The response splits or links process, compliance/readiness, and capability registers, preserves the distinct target and evidence fields for each, defines ownership and dependencies, and explains that one generic score should not silently combine the contexts.", + "assertions": [ + "separates process, compliance/readiness, and capability contexts", + "preserves distinct target and evidence criteria for each context", + "links related gaps with stable identifiers or dependencies", + "does not collapse incomparable contexts into one score", + "includes decision authority and follow-up evidence" + ], + "case_set": "dev" + } + ] +} diff --git a/gap-analysis/references/examples-and-anti-patterns.md b/gap-analysis/references/examples-and-anti-patterns.md new file mode 100644 index 0000000..a5bc3b1 --- /dev/null +++ b/gap-analysis/references/examples-and-anti-patterns.md @@ -0,0 +1,38 @@ +# Examples and Anti-Patterns + +The examples below are hypothetical teaching examples, not observed case studies. + +## Capability example + +**Question:** Can the incident team restore the payment service within the stated recovery objective? + +**Current evidence:** Two tabletop exercises restored service in 75 and 110 minutes; the target is 60 minutes; the runbook has no tested dependency fallback. **Gap:** recovery performance and tested fallback capability. **Cause hypothesis:** the fallback path is unowned and unexercised, not simply “people need training.” **Priority:** high because the consequence is material and evidence is direct. **Closure:** two representative exercises restore within 60 minutes, with named owner and captured logs. + +## Process example + +**Question:** Does every high-risk model change receive review before release? + +Current records show review for 8 of 12 changes, but the target is all changes meeting the defined risk trigger. The gap is a missing or unreliable control path. Possible causes include trigger ambiguity, workflow bypass, and capacity. Do not prescribe training until those causes are tested. The artifact is a requirement-to-record matrix with exceptions and a re-test sample. + +## Compliance/readiness example + +A launch checklist says “security complete,” but the evidence is a design review and no production-boundary test. The correct state is **implemented but unproven**, not ready. The next action is a named boundary test with acceptance criteria, not a green checkmark. + +## Research-evidence example + +A review finds studies that estimate an effect, but samples exclude the population affected by the decision and results are inconsistent. Record the gap as “not the right information” and “inconsistent,” state the decision consequence, and propose evidence that includes the relevant population and a design capable of resolving the uncertainty. “More studies” is not an adequate action. + +## Common anti-patterns + +1. **Vague target:** “Become best in class.” Replace it with an outcome, requirement, measure, horizon, and authority. +2. **Gap-as-cause:** “Lack of training” inferred from poor results. Test process, tooling, incentives, knowledge, and ownership alternatives. +3. **Score theater:** 2.7/5 with no anchors or evidence. Use anchored states or publish the scale and uncertainty. +4. **Evidence laundering:** an interview opinion becomes a fact. Label source type and corroborate when stakes warrant. +5. **Benchmark mismatch:** compare different populations, periods, denominators, or operating modes. Normalize or state the limitation. +6. **Action closure:** a policy is published, so the gap is closed. Require observed adoption or outcome evidence. +7. **Compliance overclaim:** a checklist becomes a legal conclusion. Preserve the requirement source and route interpretation. +8. **Single-template thinking:** use one matrix for capability, readiness, and research without changing the target/evidence fields. Select a variant and link related registers. + +## Stakeholder review prompts + +Ask the sponsor to challenge the target, operators to challenge the current-state evidence, affected people to challenge consequence and burden, and the accountable owner to challenge feasibility and closure evidence. Record disagreements; consensus is not evidence. diff --git a/gap-analysis/references/methodology.md b/gap-analysis/references/methodology.md new file mode 100644 index 0000000..74e3504 --- /dev/null +++ b/gap-analysis/references/methodology.md @@ -0,0 +1,58 @@ +# Methodology and Evidence + +## What it is + +ASQ defines gap analysis as comparing a current condition to a desired state. NIST's Cybersecurity Framework makes the pattern operational: an organization creates a Current Profile and Target Profile, compares them to identify gaps, and uses gap size, priority, and corrective-action cost to plan implementation. The general method transfers, but NIST categories and tiers are cybersecurity-specific. + +The generic unit is: + +`criterion -> current condition -> target condition -> difference -> consequence -> action -> closure evidence` + +A target may be a mandatory requirement, a service/outcome level, a risk-informed design objective, a strategic choice, or a research question. Name which. “Best practice” is not a target until its authority and applicability are established. + +## Scope and evidence protocol + +Write an analysis question that names the object, population, boundary, time horizon, and decision. Build a criterion register before collecting evidence. For each criterion record: + +- identifier and plain-language statement; +- source/authority, version/date, and applicability; +- measure, unit, denominator, observation period, and threshold; +- evidence sources and collection method; +- confidence and known bias/limitations; +- accountable owner and affected stakeholders. + +Triangulate when stakes justify it. Metrics show behavior but may omit context; interviews reveal experience but may be selective; documents show intended practice but not execution; tests show behavior under their scenario but not every real-world condition. Do not treat self-attestation as independent assurance. + +## Gap taxonomy + +Use one primary type and optional secondary types: + +- **Outcome/performance:** the result is below the required condition. +- **Capability/control:** a needed ability, control, or decision right is absent or unreliable. +- **Process:** work differs from the required flow, timing, quality, or handoff. +- **Resource:** people, skills, data, capacity, funding, or tooling are insufficient. +- **Knowledge/evidence:** information is missing, imprecise, biased, inconsistent, or not relevant to the decision. +- **Ownership/decision:** authority, accountability, escalation, or feedback is unclear. + +A symptom is not automatically a gap cause. “Incidents increased” is an observation; “no tested rollback path” may be a control gap; “unclear ownership” is a hypothesis until supported by records or interviews. + +## Scores and uncertainty + +Scores are communication aids, not measurements unless the scale, anchors, evidence, and aggregation rules are defined. Prefer descriptive states such as absent, partial, repeatable, measured, and continuously improved when they fit. If using a numeric scale, publish anchors and do not average incomparable dimensions. A low-confidence red score means “urgent uncertainty” may be more accurate than “worst performance.” + +## What sources support + +- NIST CSF profiles support current/target profile comparison, risk-informed outcomes, and prioritized implementation planning. NIST explicitly warns that Implementation Tiers are not necessarily maturity levels. +- GAO workforce reviews support data-driven identification, prioritization by programmatic impact, and stakeholder consultation before naming skills gaps. They also illustrate the risk of inconsistent metrics and incomplete competency data. +- CDC needs-assessment guidance supports defining the goal in relation to program outcomes and describing gaps as outcomes not currently occurring. +- AHRQ/NCBI research-gap work supports classifying where evidence falls short and why, including insufficient/imprecise, biased, inconsistent/unknown, or not-the-right information. It is a research-evidence framework, not a general organizational maturity model. +- ASQ provides the concise quality definition and examples of baseline measurement and process evidence. It does not prescribe one universal prioritization formula. + +## Minimum review questions + +1. Who set the target, and why does it apply here? +2. Is the current state observed, reported, inferred, or assumed? +3. Are current and target measured on the same unit, population, period, and boundary? +4. What consequence follows if the gap remains open? +5. Which causes are evidenced, and which are hypotheses? +6. What would prove closure, and who can accept that evidence? diff --git a/gap-analysis/references/prioritization-and-roadmaps.md b/gap-analysis/references/prioritization-and-roadmaps.md new file mode 100644 index 0000000..8146ccc --- /dev/null +++ b/gap-analysis/references/prioritization-and-roadmaps.md @@ -0,0 +1,44 @@ +# Prioritization and Roadmaps + +## Choose criteria before ranking + +Prioritization is a decision, not a property hidden inside a gap. Agree on criteria with the sponsor and record weights only when numerical weighting improves consistency. Typical criteria include consequence/impact, urgency or exposure, affected reach, confidence, feasibility, cost, dependency leverage, reversibility, and equity or non-negotiable constraints. + +A simple qualitative grid is often better than false precision: + +| Priority | Meaning | +|---|---| +| Critical | Immediate consequence or hard gate; action/decision required before proceeding | +| High | Material outcome, risk, or dependency; schedule in the next planning window | +| Medium | Valuable improvement with manageable exposure; sequence after higher-leverage work | +| Low | Useful but weakly consequential, exploratory, or dependent on unresolved evidence | +| Hold | Do not act until a named uncertainty or decision is resolved | + +If using a score, publish the formula, anchors, weights, missing-data behavior, and sensitivity. Do not let confidence disappear inside impact. A high-impact, low-confidence finding may deserve validation first, not automatic remediation. + +## From gaps to actions + +Every selected gap becomes an action or an evidence-gathering task with: + +- gap ID and desired closure condition; +- accountable owner and responsible implementer; +- action, deliverable, dependency, and resource; +- due date or trigger, with rationale; +- acceptance evidence and reviewer/decision authority; +- residual risk and fallback if the target cannot be met; +- follow-up measure and review date. + +Use a dependency-aware sequence: first resolve target ambiguity and high-consequence unknowns, then address enabling capabilities, then change the process/control, then measure the outcome. Do not confuse “training delivered,” “policy published,” or “ticket closed” with closure unless the target is implementation activity itself. + +## Roadmap review + +At each review, show open/closed/blocked/held gaps, evidence added, target changes, residual risk, overdue actions, and whether the intervention changed the outcome. Reopen a gap when the closure test fails or the target changes. Preserve the original observation and target version so trend lines do not rewrite history. + +## Anti-patterns + +- Ranking by gap size alone when consequences differ. +- Treating every gap as a project instead of asking whether the target should change. +- Applying a universal red/amber/green threshold across incomparable contexts. +- Closing a finding because a plan exists. +- Hiding a low-confidence estimate behind a precise decimal score. +- Prioritizing what is easiest while calling it highest value. diff --git a/gap-analysis/references/source-index.md b/gap-analysis/references/source-index.md new file mode 100644 index 0000000..92cd843 --- /dev/null +++ b/gap-analysis/references/source-index.md @@ -0,0 +1,16 @@ +# Source Index + +Accessed 2026-09-07. Sources are retained as pointers and claims are paraphrased in original language. Vendor and consultancy pages are not used as normative authority. + +| ID | Source | Authority/type | Supports | Limits | +|---|---|---|---|---| +| S1 | [ASQ Quality Glossary](https://asq.org/quality-resources/quality-glossary) | Professional quality body | Concise definition: compare current condition with desired state; baseline/data tools | Short definition, not a full method | +| S2 | [NIST CSF 2.0](https://www.nist.gov/cyberframework) and [components](https://www.nist.gov/cyberframework/cybersecurity-framework-11-components) | U.S. standards agency | Current/Target Profiles, risk-informed outcomes, prioritized implementation; tiers are not necessarily maturity levels | Cybersecurity-specific; voluntary framework | +| S3 | [NIST SP 1301](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.1301.pdf) | U.S. standards agency | Profile creation and current/target comparison workflow | Cybersecurity-specific | +| S4 | [GAO-15-223](https://www.gao.gov/products/gao-15-223) | U.S. government audit/evaluation body | Data-driven gap identification, programmatic-impact prioritization, stakeholder consultation, metric consistency | Federal workforce case; recommendations are context-bound | +| S5 | [CDC needs analysis](https://www.cdc.gov/training-development/php/about/assess-training-needs-conducting-needs-analysis.html) | U.S. public health agency | Tie the assessment goal to program outcomes and describe gaps as outcomes not occurring | Training/needs-assessment context | +| S6 | [AHRQ/NCBI research-gap framework](https://www.ncbi.nlm.nih.gov/books/NBK126702/) | U.S. evidence-synthesis method | Characterize where evidence falls short and why: insufficient/imprecise, biased, inconsistent/unknown, not right information; distinguish gaps from decision-relevant needs | Research evidence context, not organizational maturity | +| S7 | [AHRQ Gap Analysis Facilitator's Guide](https://www.ahrq.gov/patient-safety/settings/hospital/candor/modules/facguide3.html) | U.S. health quality agency | Document review, focus groups, structured interviews, priorities, report template | Healthcare program context | +| S8 | [UK National Archives Gap Analysis Study](https://cdn.nationalarchives.gov.uk/documents/gap_analysis.pdf) | Government archive | Worked public-sector gap-analysis example | Source should be rechecked if used for a specific current claim | + +Do not cite S2-S7 as if they establish one universal gap-analysis standard. They are complementary examples of a recurring method in different domains. diff --git a/gap-analysis/references/variants.md b/gap-analysis/references/variants.md new file mode 100644 index 0000000..c34de74 --- /dev/null +++ b/gap-analysis/references/variants.md @@ -0,0 +1,35 @@ +# Context Variants + +Use the generic method, then adapt the target and evidence to the context. Never import a framework's scale or threshold without its authority and fit. + +## Capability and maturity + +Assess capabilities as observable behaviors, not labels. Define levels with anchors such as intent, repeatability, measurement, integration, and adaptation only when those levels serve the decision. Evidence can include operating records, demonstrations, outcomes, ownership, and review cadence. Report capability-by-capability rather than one blended maturity number. A maturity model can show progression; it cannot prove business value by itself. + +**Artifact:** capability statement, level anchors, current evidence, desired level rationale, dependency map, and staged roadmap. + +## Process and operating model + +Map the actual flow, handoffs, decision rights, queues, controls, and outcomes. Compare the flow to the required or desired flow. Look for wait states, rework, missing inputs, conflicting incentives, and unowned exceptions. Validate with records and people who perform the work, not only the process owner. + +**Artifact:** process step matrix with owner, input, output, control, measure, failure mode, current evidence, target behavior, and change action. + +## Compliance and readiness + +Start with an authoritative requirement or release criterion and preserve its wording and applicability. Map each requirement to implementation status, evidence, owner, and residual uncertainty. Distinguish “not implemented,” “implemented but unproven,” “not applicable with rationale,” and “evidence unavailable.” Do not declare legal compliance, certification, or audit readiness from a self-assessment. Route interpretation to qualified legal, compliance, audit, security, quality, or regulatory owners. + +**Artifact:** requirement-to-evidence matrix plus exceptions, remediation plan, acceptance authority, and re-test plan. + +## Research and evidence gaps + +Define the decision question and the population/intervention/comparison/outcome/setting as applicable. Describe what the evidence does and does not establish, then classify why it falls short: insufficient/imprecise, biased, inconsistent/unknown, or not the right information. A research gap becomes a research need only when filling it would help a real decision-maker. Specify the study or evidence needed, not just “more research.” + +**Artifact:** question/evidence matrix, gap reason, decision consequence, priority criteria, and proposed evidence design. + +## Readiness and transition + +Define the go/no-go condition, date, operating boundary, dependencies, rehearsal evidence, rollback or fallback, and owner. Readiness is not the same as activity completion. Mark each criterion as demonstrated, partially demonstrated, untested, blocked, or not applicable with rationale. Use a decision gate with explicit residual risks and authority. + +## Selecting a variant + +If a request mixes contexts, split the analysis into linked registers. For example, a compliance gap can expose a capability gap and a readiness dependency, but one row should not silently carry three different standards. Maintain a stable gap ID and link related rows. diff --git a/gap-analysis/scripts/validate-register.py b/gap-analysis/scripts/validate-register.py new file mode 100644 index 0000000..15bbde6 --- /dev/null +++ b/gap-analysis/scripts/validate-register.py @@ -0,0 +1,48 @@ +#!/usr/bin/env python3 +"""Validate the required fields of a JSON gap register.""" +import argparse +import json +import sys +from pathlib import Path + +REQUIRED = ("id", "question", "target", "current", "evidence", "priority", "owner", "closure_test") + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("path", type=Path) + args = parser.parse_args() + try: + data = json.loads(args.path.read_text()) + except (OSError, json.JSONDecodeError) as exc: + print(f"error: cannot read JSON register: {exc}", file=sys.stderr) + return 2 + gaps = data.get("gaps") if isinstance(data, dict) else None + if not isinstance(gaps, list): + print("error: top-level 'gaps' must be an array", file=sys.stderr) + return 2 + errors = [] + ids = set() + for index, gap in enumerate(gaps, 1): + prefix = f"gaps[{index}]" + if not isinstance(gap, dict): + errors.append(f"{prefix}: must be an object") + continue + for field in REQUIRED: + if not isinstance(gap.get(field), str) or not gap[field].strip(): + errors.append(f"{prefix}: missing non-empty {field!r}") + gap_id = gap.get("id") + if gap_id in ids: + errors.append(f"{prefix}: duplicate id {gap_id!r}") + ids.add(gap_id) + evidence = gap.get("evidence") + if isinstance(evidence, str) and evidence.strip().lower() in {"tbd", "unknown", "none"}: + if not isinstance(gap.get("evidence_gap"), str) or not gap["evidence_gap"].strip(): + errors.append(f"{prefix}: unknown evidence requires an explicit evidence_gap") + if errors: + print("\n".join(f"error: {error}" for error in errors), file=sys.stderr) + return 1 + print(f"validated {len(gaps)} gap(s)") + return 0 + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/gap-analysis/templates/capability-assessment.md b/gap-analysis/templates/capability-assessment.md new file mode 100644 index 0000000..5916a78 --- /dev/null +++ b/gap-analysis/templates/capability-assessment.md @@ -0,0 +1,19 @@ +# Capability Assessment + +## Decision +- Capability/system: +- Decision this assessment informs: +- Scope and exclusions: +- Horizon: + +## Capability model + +| Capability | Observable behavior/outcome | Level anchors used | Current evidence | Desired level and rationale | Gap ID | Dependencies | +|---|---|---|---|---|---|---| +| | | | | | | | + +## Review +- Evidence that the capability is performed, not merely documented: +- Self-assessment limitations: +- Stakeholders consulted: +- Follow-up demonstration or measure: diff --git a/gap-analysis/templates/compliance-readiness-assessment.md b/gap-analysis/templates/compliance-readiness-assessment.md new file mode 100644 index 0000000..851c720 --- /dev/null +++ b/gap-analysis/templates/compliance-readiness-assessment.md @@ -0,0 +1,23 @@ +# Compliance or Readiness Assessment + +This is a self-assessment artifact, not a legal opinion, certification, or audit report. + +| Requirement/gate ID | Source, version, applicability | Required condition | Current implementation | Evidence artifact and date | Status | Gap ID | Owner | Acceptance authority | +|---|---|---|---|---|---|---|---|---| +| | | | | | | | | | + +## Status meanings + +- **Met and evidenced:** the condition and evidence match the scope. +- **Implemented, unproven:** a control exists but its operation or boundary has not been demonstrated. +- **Partial:** only part of the condition is met. +- **Not met:** evidence shows the condition is absent. +- **Not applicable:** documented rationale and approving authority required. +- **Unknown:** evidence unavailable or contradictory; do not treat as met. + +## Release decision +- Decision owner: +- Decision date/trigger: +- Blocking gaps: +- Residual risk and fallback: +- Re-test plan: diff --git a/gap-analysis/templates/gap-register.md b/gap-analysis/templates/gap-register.md new file mode 100644 index 0000000..b9ca8b3 --- /dev/null +++ b/gap-analysis/templates/gap-register.md @@ -0,0 +1,29 @@ +# Gap Register + +Use one row per bounded gap. Keep the register linked to source evidence and a roadmap. + +| Field | Entry | +|---|---| +| Gap ID | `G-###` | +| Decision/question | | +| Scope/boundary/time horizon | | +| Criterion / target condition | | +| Target authority and version/date | | +| Current condition | | +| Current evidence / source IDs | | +| Measure, unit, period, population | | +| Difference and consequence | | +| Gap type | outcome / capability / process / resource / evidence / ownership | +| Cause hypotheses (separate from facts) | | +| Confidence and limitations | high / medium / low, with rationale | +| Priority and criteria rationale | | +| Accountable owner / responsible implementer | | +| Action or evidence task | | +| Dependency / resource / due trigger | | +| Closure test and accepting authority | | +| Residual risk / fallback | | +| Status and last reviewed | open / active / blocked / held / closed | + +## Row discipline + +Do not leave target, evidence, owner, or closure test implied. If a field is unknown, write `unknown`, explain why, and create an evidence task when the uncertainty affects the decision. diff --git a/gap-analysis/templates/process-gap-analysis.md b/gap-analysis/templates/process-gap-analysis.md new file mode 100644 index 0000000..401f478 --- /dev/null +++ b/gap-analysis/templates/process-gap-analysis.md @@ -0,0 +1,15 @@ +# Process Gap Analysis + +## Process boundary +- Outcome: +- Start event / end event: +- Actors and decision rights: +- In scope / out of scope: + +| Step/handoff | Required input/output | Current behavior and evidence | Target behavior/control | Failure or wait signal | Gap ID | Owner | +|---|---|---|---|---|---|---| +| | | | | | | | + +## Action plan +| Gap ID | Root-cause hypothesis to test | Change/evidence task | Acceptance measure | Dependency | Accountable owner | Review date | +|---|---|---|---|---|---|---| diff --git a/gap-analysis/templates/research-evidence-gap.md b/gap-analysis/templates/research-evidence-gap.md new file mode 100644 index 0000000..f200de5 --- /dev/null +++ b/gap-analysis/templates/research-evidence-gap.md @@ -0,0 +1,16 @@ +# Research-Evidence Gap + +## Decision question +- Population/context: +- Intervention/exposure: +- Comparison: +- Outcome: +- Setting/time: +- Decision-maker and consequence: + +| Gap ID | What the evidence can establish | What it cannot establish | Gap reason | Affected population/context | Evidence quality/limitations | Priority rationale | Evidence needed | Owner | +|---|---|---|---|---|---|---|---|---| +| | | | insufficient/imprecise; biased; inconsistent/unknown; not right information | | | | | | + +## Synthesis boundary +State whether this is an evidence gap, a research need, or both. Do not recommend “more research” without naming the unresolved decision, relevant design/population, and result that would change the decision. diff --git a/llms.txt b/llms.txt index b5d4a09..31e3f4c 100644 --- a/llms.txt +++ b/llms.txt @@ -55,6 +55,7 @@ - [forgejo-cli](forgejo-cli/SKILL.md): Use when managing a Forgejo or Gitea server from the terminal: issues, pull requests, repositories, file contents, labels, milestones, releases, webhooks, user settings, or any /api/v1 endpoint through a safe generic API command. Do not use this skill for unrelated requests; route to the nearest named specialist. - [forward-deployed-engineering](forward-deployed-engineering/SKILL.md): Guide embedded technical engagements from ambiguous stakeholder need through discovery, framing, hypothesis, build, evaluation, deployment, adoption, measurement, and generalization while preserving evidence, decision rights, and field learning. Use when one accountable technical lead must carry continuity across customer or stakeholder discovery, implementation, production fit, adoption, and measurable outcomes. Do not use for a bounded repository change, product investment governance, ongoing reliability or platform ownership, an isolated specialist task, or advisory work that ends before implementation and adoption. - [frontend-engineering](frontend-engineering/SKILL.md): Build and maintain web frontends — component architecture, state management, API integration, responsive layout, client-side performance, and frontend testing patterns. Framework agnostic, focused on web frontend implementation. Do not use for backend service implementation, data engineering, or platform infrastructure work. +- [gap-analysis](gap-analysis/SKILL.md): Analyze gaps by comparing a defined current state with a justified target state, characterizing causes and uncertainty, prioritizing actionable interventions, and producing traceable matrices, roadmaps, and decision records. Use for capability, process, compliance, readiness, maturity, operating-model, or research-evidence gaps. Do not use for a vague list of problems, a standalone root-cause analysis, a generic SWOT, or legal or audit certification advice without a governing standard and qualified owner. - [genius-life](genius-life/SKILL.md): Guide a person in cultivating creativity in their own work and life: open conversational sessions on creative blocks, habits, environment, motivation, and resilience, or structured development of a concrete project or fledgling idea through a five-phase practice. Do not use for therapy or clinical support, general life coaching, product or stakeholder discovery, or as a study guide for a book. - [ghost](ghost/SKILL.md): Manage Ghost CMS content over the Admin API — browse posts, pages, and tags, draft and publish content, schedule posts, and inspect site info from the terminal. Do not use this skill for Ghost server installation or site administration (installing, nginx, SSL, systemd, updates); those belong to the official npm ghost-cli tooling. - [github-runner](github-runner/SKILL.md): Deploy, manage, and troubleshoot self-hosted GitHub Actions runners. Covers systemd service, Docker containers, Kubernetes (Actions Runner Controller), and the Scale Set Client. Use when setting up a CI runner, debugging registration failures, designing autoscaling, or hardening runner security. Do not use this skill for unrelated requests; route to the nearest named specialist.