diff --git a/formats/enhancement-report.md b/formats/enhancement-report.md new file mode 100644 index 0000000..5be574a --- /dev/null +++ b/formats/enhancement-report.md @@ -0,0 +1,141 @@ + + + +--- +name: enhancement-report +type: format +description: > + Output format for prompt asset enhancement. Structures asset + identification, provenance and version detection, a capability baseline, a + prioritized enhancement plan classified by the enhancement-categories + taxonomy, application status, residual gaps, and coverage. +produces: enhancement-report +--- + +# Format: Enhancement Report + +The output MUST be a structured enhancement report. The report accompanies the +enhancement work in both modes: in **document mode** it is the sole +deliverable (a plan); in **action mode** it records what was applied to the +asset. + +The report uses a **single required structure** (defined under Document +Structure below). Every section is required; do **not** omit a section. If a +section has no content, state "None identified" (or, for Applied Changes in +document mode, "Not applicable — document mode"). + +## Status and Priority Vocabularies + +- **Enhancement status** (one per opportunity): + - **Proposed** — identified and offered; not yet acted on (document mode, or + awaiting confirmation). + - **Applied** — confirmed and written into the asset (action mode). + - **Deferred** — confirmed relevant but intentionally not applied this pass; + state why. + - **Skipped** — excluded by the user's focus, or declined; state why. +- **Priority**: High / Medium / Low, per the `enhancement-categories` + taxonomy's priority guidance. Do not invent a different scale. + +## Document Structure + +The report MUST include the following sections in this exact order. Sections +**1-8** are required. Do **not** omit a section; if a section has no content, +state "None identified" (or, for Applied Changes in document mode, "Not +applicable — document mode"). If there are **zero** opportunities, state "None +identified" in the Enhancement Plan and record what was examined in Coverage. + +```markdown +# — Enhancement Report + +## 1. Executive Summary +<2-4 sentences for stakeholders: what asset was assessed, its provenance and +detected version, the count and highest priority of opportunities, and the +overall recommendation or what was applied. Understandable on its own.> + +## 2. Asset Summary +- **Type**: +- **Files**: +- **Intent**: +- **Mode**: +- **Focus**: + +## 3. Provenance and Version Detection +- **Provenance**: +- **Detected version**: +- **Evidence**: + +## 4. Capability Baseline + | +| Guardrails | Full / Partial / Absent | | +| Analysis / reasoning | Full / Partial / Absent | | +| Output format | Full / Partial / Absent | | +| Taxonomy | Full / Partial / Absent | | + +List preserved user customizations below the table, or "None identified".> + +## 5. Enhancement Plan +: +- **Category**: +- **Target**: +- **Source component**: +- **Change**: +- **Preserves**: +- **Priority**: High / Medium / Low +- **Status**: Proposed / Applied / Deferred / Skipped +- **Rationale**: + +If no opportunities exist, state "None identified".> + +## 6. Applied Changes + + +## 7. Residual Gaps and Follow-ups + + +## 8. Coverage +- **Examined**: +- **Method**: +- **Excluded**: +- **Limitations**: +``` + +## Formatting Rules + +- Opportunities MUST be ordered by priority (High first), then by the + `enhancement-categories` Ranking Criteria. +- Every opportunity MUST carry exactly one taxonomy label and a status. +- Every opportunity that edits existing text MUST name the customizations it + preserves (or "n/a"). +- Evidence MUST be concrete — cite asset locations and name source components; + do not describe changes vaguely. +- The executive summary MUST be understandable without reading the rest. +- The report MUST distinguish E2 (new capability) from E3 (version upgrade) + consistently with the provenance recorded in the Provenance and Version + Detection section — an E3 label requires PromptKit provenance evidence. +- The Coverage section MUST include all four fields — Examined, Method, + Excluded, Limitations — per the `self-verification` protocol. diff --git a/manifest.yaml b/manifest.yaml index f4d063c..a0ed2ec 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -625,6 +625,15 @@ protocols: segments. Maps each to existing library components or marks as novel for assimilation. + - name: prompt-enhancement + path: protocols/reasoning/prompt-enhancement.md + description: > + Reasoning protocol for enhancing an existing prompt asset with + current PromptKit capabilities. Covers ingestion, provenance and + version detection, capability baselining, gap analysis against the + library, enhancement proposal, in-place application, and + verification. Preserves original intent and user customizations. + - name: manufacturing-artifact-generation path: protocols/reasoning/manufacturing-artifact-generation.md description: > @@ -760,6 +769,16 @@ formats: as a scheduled or event-driven automation running in GitHub Actions with a coding agent. Requires `gh aw` CLI for compilation. + - name: enhancement-report + path: formats/enhancement-report.md + produces: enhancement-report + description: > + Output format for prompt asset enhancement. Structures asset + identification, provenance and version detection, a capability + baseline, a prioritized enhancement plan classified by the + enhancement-categories taxonomy, application status, residual gaps, + and coverage. + - name: implementation-plan path: formats/implementation-plan.md produces: implementation-plan @@ -945,6 +964,16 @@ taxonomies: context hoarding, premature optimization, and ephemeral memory failure. + - name: enhancement-categories + path: taxonomies/enhancement-categories.md + domain: prompt-asset-enhancement + description: > + Classification scheme (E1-E8) for enhancement opportunities when + upgrading an existing prompt asset with PromptKit capabilities. Covers + missing guardrails, new capabilities, version upgrades, format + modernization, determinism hardening, persona/expertise gaps, + structural decomposition, and provenance stamping. + - name: cwe-cli-tools path: taxonomies/cwe-cli-tools.md domain: cli-tools @@ -1657,6 +1686,20 @@ templates: persona: systems-engineer protocols: [anti-hallucination, self-verification, session-handoff] + - name: enhance-prompt + path: templates/enhance-prompt.md + description: > + Enhance an existing prompt asset (raw prompt, Copilot prompt file, + agent definition, instruction/skill file, or a combination) with + current PromptKit capabilities. Detects PromptKit provenance, + baselines current capabilities, performs a gap analysis against the + library, and proposes prioritized, category-classified enhancements. + Supports document mode (plan) or action mode (apply in place). + persona: promptkit-contributor + protocols: [anti-hallucination, self-verification, prompt-enhancement] + taxonomies: [enhancement-categories] + format: enhancement-report + contribution: - name: extend-library path: templates/extend-library.md diff --git a/protocols/reasoning/prompt-enhancement.md b/protocols/reasoning/prompt-enhancement.md new file mode 100644 index 0000000..ed6087f --- /dev/null +++ b/protocols/reasoning/prompt-enhancement.md @@ -0,0 +1,212 @@ + + + +--- +name: prompt-enhancement +type: reasoning +description: > + Reasoning protocol for enhancing an existing prompt asset (prompt, agent + file, instruction file, or a combination) with current PromptKit + capabilities. Walks through ingestion, provenance and version detection, + capability baselining, gap analysis against the current library, enhancement + proposal, in-place application, and verification. Preserves the asset's + original intent and user customizations throughout. +applicable_to: + - enhance-prompt +--- + +# Protocol: Prompt Enhancement + +Apply this protocol when enhancing an existing prompt asset with PromptKit +capabilities. A "prompt asset" is any LLM-facing instruction artifact: a raw +prompt, a Copilot prompt file, an agent definition, an instruction/skill file, +or a combination of these. Execute the phases in order. Do NOT apply any change +to the asset until Phase 6, and only after the user confirms. + +This protocol composes additively with `anti-hallucination` and +`self-verification`: base every claim about the asset and the library on +content you actually read, and run the self-verification gate before +finalizing. + +## Phase 1: Asset Ingestion and Classification + +1. **Read the asset(s) in full.** If file paths are provided, read each file. + If inline content is provided, use it directly. For a combination (e.g., an + agent file plus several instruction files), read every file and record the + set. +2. **Classify each asset's type** as exactly one of: + - **Raw prompt** — a standalone prompt for a fresh LLM session. + - **Copilot prompt file** — a `.github/prompts/*.prompt.md` slash command + (has `description` and `agent` frontmatter; `tools` is optional). + - **Agent definition** — a custom agent file (e.g., + `.github/agents/*.agent.md`). + - **Instruction / skill file** — a persistent file auto-loaded by a runtime + (e.g., `.github/instructions/*.instructions.md` with `applyTo`, + `CLAUDE.md`, `.cursorrules`). + - **Mixed set** — a combination; record each member's type. +3. **Extract the asset's intent.** State, in one or two sentences, the task the + asset is built to perform, its inputs, and its expected output. Mark the + intent `[KNOWN]` when stated in the asset, `[INFERRED]` when derived from + its content, and ask the user when it cannot be determined. +4. **Record structure.** Note the asset's existing sections, rules, identity + framing, and any `{{param}}` / `${input:...}` / `${{ }}` placeholders, so + later phases can target additions without disturbing them. + +## Phase 2: Provenance and Version Detection + +Determine whether the asset was previously generated or shaped by PromptKit. +This phase **degrades gracefully**: absence of a marker is a valid, common +result, not a failure. + +1. **Search for an explicit provenance marker.** Look for a + `` comment or any embedded statement of + PromptKit origin. If a version is present in the marker, record it as the + **detected version** `[KNOWN]`. +2. **Search for structural provenance.** When no explicit marker exists, look + for recognizable PromptKit structure: section headers such as `# Identity`, + `# Reasoning Protocols`, `# Output Format`, `# Non-Goals`; a `# Session + Name` header; or verbatim phrasing matching known components. Record this as + **inferred provenance** `[INFERRED]` and name the evidence. +3. **Classify provenance** as one of: + - **PromptKit provenance detected, version known** — marker with a version. + - **PromptKit provenance detected, version unknown** — marker or strong + structural match, but no recoverable version. + - **No PromptKit provenance detected** — no marker and no structural match. +4. **Set the upgrade eligibility.** Version upgrades (E3) are eligible only + when there is **provenance evidence tied to a specific component**: an + explicit PromptKit marker, OR a strong content-level match showing the asset + embodies an older version of a specific, identifiable current component + (confirmed in Phase 4 by reading that component). Generic PromptKit-like + structure alone is NOT sufficient for E3. When provenance is absent, + ambiguous, or cannot be tied to a specific component, treat every gap as a + new capability (E2). Do NOT fabricate a prior version or guess a version + number. + +## Phase 3: Capability Baseline Inventory + +Inventory what PromptKit-equivalent capabilities the asset already has, so +Phase 4 proposes only genuine gaps. + +1. **Map present capabilities to PromptKit layers.** For each PromptKit layer, + record whether the asset already embodies it and how: + - **Persona / identity** — is there explicit expertise framing? + - **Guardrails** — are there anti-hallucination, self-verification, or + scoping rules (even if phrased differently)? + - **Analysis / reasoning methodology** — are there ordered, domain-specific + or systematic reasoning steps? + - **Output format** — is there a section contract or structure rule? + - **Taxonomy** — is there a classification or severity scheme? +2. **Record coverage strength** for each present capability as Full, Partial, + or Absent, with a one-line rationale citing the asset location. +3. **Note user customizations.** Flag any content that appears to be a + deliberate, asset-specific choice (project conventions, banned APIs, tone, + domain rules). These MUST be preserved through any later edit. + +## Phase 4: Gap Analysis Against the Current Library + +Compare the baseline (Phase 3) against the current PromptKit library to +discover enhancement opportunities. + +1. **Read the current manifest.** Read `manifest.yaml` to enumerate the + components available now (personas, protocols, formats, taxonomies, + templates). +2. **Match the asset's task to library components.** Identify the template(s) + whose domain matches the asset's intent, and the personas, protocols, + taxonomies, and formats those templates use. These are the strongest + candidates for relevant capabilities. +3. **Read the candidate component files.** Before classifying or proposing, + open and read the full text of each candidate component (persona, protocol, + format, taxonomy) identified in step 2 — manifest descriptions alone are + insufficient. Content-level reading is required to judge present coverage, + to compare an older embodied version against the current component for E3, + to synthesize accurate capability text in Phase 6, and to satisfy the + `anti-hallucination` grounding requirement. +4. **Identify each gap and classify it** using the `enhancement-categories` + taxonomy (E1–E8), applying that taxonomy's **Disambiguation and Precedence** + rules so every gap receives exactly one label. For each gap, record: + - The taxonomy label (exactly one). + - The specific source PromptKit component or convention that would close it. + - The target location in the asset. + - A priority per the taxonomy's priority guidance. +5. **Distinguish E2 from E3 by provenance evidence.** Label a gap **E3 + (version upgrade)** only when Phase 2 established provenance evidence tied to + a specific component AND the component file you read in step 3 is a newer + version of what the asset already embodies. Otherwise label it **E2 (new + capability)**. Never label E3 from generic PromptKit-like structure alone, + and never fabricate a prior version. +6. **Reject non-gaps.** If the asset already has Full coverage of a capability + (Phase 3), do not propose adding it. Apply `anti-hallucination` scope + boundaries — do not invent gaps to appear thorough. + +## Phase 5: Enhancement Proposal + +Produce a prioritized, classified enhancement plan and present it for +confirmation. + +1. **Apply the user's focus, if any.** If the user named focus categories + (by numeric ID E1–E8 or full label ID such as E1_MISSING_GUARDRAIL), include + only opportunities in those categories in the actionable plan; record the + rest under "Residual Gaps." If no focus was given, include all discovered + opportunities and let the user select. +2. **Order the plan** by priority, then by the taxonomy's Ranking Criteria. +3. **For each proposed enhancement, specify:** an ID, the taxonomy label, the + target location, the source component/convention, the concrete change in + one or two sentences, the priority, and an initial status of `Proposed`. +4. **State preservation guarantees.** For every enhancement that edits existing + text, name the user customizations (Phase 3.3) it must preserve. +5. **Present the plan and stop.** Do NOT apply any change until the user + confirms which enhancements to apply. This confirmation gate is mandatory. + +## Phase 6: Enhancement Application (Action Mode) + +Execute only after the user confirms, and only for confirmed enhancements. In +document mode, skip this phase — the plan and report are the deliverable. + +1. **Apply one enhancement at a time**, in priority order. Re-read the target + region immediately before editing it. +2. **Confirm file-level operations separately.** Most enhancements edit the + asset in place. When an enhancement creates, renames, splits, or deletes + files (e.g., E7 splitting a monolith into composable skill files), first + present the complete proposed file set — each path and its operation + (create / rename / delete) — and obtain explicit confirmation before + writing. Never create, rename, or delete a file the user did not confirm. +3. **Preserve intent and customizations.** Integrate PromptKit capabilities + without removing or overriding the asset's original task intent or the user + customizations flagged in Phase 3.3. When a customization conflicts with a + standard component, keep the customization and note the deviation. +4. **Synthesize in the asset's native form.** Express each capability in the + asset's own type and style — section text for a raw prompt, frontmatter plus + body for a Copilot prompt file, `applyTo`-scoped directives for an + instruction/skill file. Do not paste raw component files verbatim where the + asset's format calls for adaptation. +5. **Preserve placeholder syntax.** Keep the asset's existing parameter syntax + (`{{param}}`, `${input:param}`, `${{ }}`) intact; match it when adding new + variable content. +6. **Update provenance (E8) last.** If the user accepted a provenance stamp, + add or update a `` marker recording the + components applied in this pass and the current PromptKit version. Source + the version from the top-level `version:` scalar in the library's + `manifest.yaml` (the same source `bootstrap.md` uses); if it cannot be read, + write "version unknown" rather than guessing a number. +7. **Record final status.** Mark each applied enhancement `Applied`. Mark an + enhancement `Deferred` (with a reason) when the user chose to postpone it, + and `Skipped` when the user declined it or it was excluded by focus. + +## Phase 7: Verification + +Before finalizing, verify the enhanced asset and the report. + +1. **Coherence check.** Re-read the enhanced asset end to end. Confirm it reads + as a single coherent instruction set with no duplicated, contradictory, or + orphaned rules introduced by the additions. +2. **Intent preservation check.** Confirm the asset still performs its original + task (Phase 1.3) and that every Phase 3.3 customization survives. +3. **No-regression check.** Confirm no existing capability was weakened or + removed except where the user explicitly approved a replacement (E3/E4). +4. **Determinism check on additions.** Apply the `self-verification` + determinism rule to any directive text you added, so the enhancement does + not itself introduce vague language. +5. **Report accuracy check.** Confirm every enhancement in the report has a + correct final status (Proposed / Applied / Deferred / Skipped) and that + Residual Gaps lists everything discovered but not applied, including + focus-excluded (Skipped) and low-priority items (e.g., E8 when deferred). diff --git a/taxonomies/enhancement-categories.md b/taxonomies/enhancement-categories.md new file mode 100644 index 0000000..4c5d661 --- /dev/null +++ b/taxonomies/enhancement-categories.md @@ -0,0 +1,269 @@ + + + +--- +name: enhancement-categories +type: taxonomy +description: > + Classification scheme (E1-E8) for enhancement opportunities when upgrading + an existing prompt asset (prompt, agent file, or instruction file) with + PromptKit capabilities. Covers missing guardrails, newly-available + components, version upgrades, format modernization, determinism hardening, + persona/expertise gaps, structural decomposition, and provenance stamping. +domain: prompt-asset-enhancement +applicable_to: + - enhance-prompt +--- + +# Taxonomy: Enhancement Categories + +Use these labels to classify enhancement opportunities when upgrading an +existing prompt asset — a raw prompt, agent file, instruction file, or a +combination — with PromptKit capabilities. Every proposed enhancement MUST +use exactly one label from this taxonomy. + +## Dual Use + +This taxonomy serves two roles in the `enhance-prompt` workflow: + +1. **User focus selector (input).** The user MAY name one or more labels (by + numeric ID E1–E8, or full label ID such as E1_MISSING_GUARDRAIL) to scope + the enhancement to specific areas. When a focus is set, only opportunities + in the named categories are proposed; others are recorded under "Residual + Gaps" but not applied. +2. **Classification scheme (output).** When the user does NOT specify a focus, + the workflow analyzes the asset, discovers opportunities across all + categories, and labels each one. The user then selects which to apply. + +## Label Summaries + +- **E1 (Missing Guardrail)**: The asset lacks a cross-cutting PromptKit + guardrail that constrains fabrication, verification, or scope. +- **E2 (New Capability)**: A relevant PromptKit component exists that the + asset does not reflect, independent of when the asset was authored. +- **E3 (Version Upgrade)**: A component the asset already embodies has since + been improved; re-applying its current version upgrades the asset. +- **E4 (Format Modernization)**: The asset's output structure is ad hoc, + incomplete, or inconsistent with current PromptKit format conventions. +- **E5 (Determinism Hardening)**: The asset contains vague language that two + LLMs would interpret differently. +- **E6 (Persona/Expertise Gap)**: The asset lacks explicit, task-appropriate + expertise framing. +- **E7 (Structural Decomposition)**: The asset mixes concerns in a monolith + that should be separated into layers or composable files. +- **E8 (Provenance Stamp)**: The asset lacks a PromptKit provenance/version + marker that would enable future enhancement passes. + +## Labels + +### E1_MISSING_GUARDRAIL + +The asset performs a task that produces human- or LLM-consumed output but +lacks a cross-cutting PromptKit guardrail — anti-hallucination (epistemic +labeling, refusal to fabricate, source attribution), self-verification +(pre-finalization quality gate), or operational-constraints (scoping, tool +use, deterministic analysis). + +**Signals**: No instruction to distinguish known/inferred/assumed claims; no +"cite your sources" or "do not invent" rule; no self-check or verification +step before finalizing; no scope or context-management guidance for a task +that reads large inputs. + +**Example enhancement**: Add the `anti-hallucination` epistemic-labeling rules +and a `self-verification` pre-submission checklist to a code-review prompt +that currently asks only "find bugs." + +**Priority guidance**: High when the asset drives decisions, modifies code, or +produces externally visible output. Medium for read-only summarization tasks. + +### E2_NEW_CAPABILITY + +A PromptKit component (persona, protocol, format, or taxonomy) exists in the +current library that is directly relevant to the asset's task and would add +value, but the asset does not reflect it. Unlike E3, this does not depend on +the asset's provenance — the capability is simply absent. + +**Signals**: The asset's task maps to an existing template's domain (e.g., +memory-safety review, security audit, requirements authoring) but omits the +corresponding analysis protocol or taxonomy; the manifest contains a component +whose description matches an uncovered need in the asset. + +**Example enhancement**: Add the `memory-safety-c` analysis protocol and the +`stack-lifetime-hazards` taxonomy to a C code-review prompt that reviews only +for "correctness." + +**Priority guidance**: High when the missing capability covers a safety- or +security-relevant gap. Medium for capabilities that improve thoroughness. +Low for tangential additions. + +### E3_VERSION_UPGRADE + +The asset embodies an older version of a specific, identifiable PromptKit +component that has since been improved, expanded, or corrected. Re-applying the +component's current version upgrades the asset. Requires **provenance evidence +tied to a specific component**: an explicit PromptKit marker, OR a strong +content-level match to a specific existing component. When no such evidence +exists — generic PromptKit-like structure is not enough — classify the same +content gap as E2 instead. Never fabricate a prior version. + +**Signals**: An explicit PromptKit provenance marker, OR content that is +demonstrably an older, shorter, or superseded version of a specific current +component (fewer phases, missing rules, renamed sections) identified by reading +that component. + +**Example enhancement**: Replace an older 3-rule embedded anti-hallucination +block with the current 5-rule `anti-hallucination` protocol, preserving any +user edits layered on top. + +**Priority guidance**: High when the upgraded component fixes a correctness or +safety gap. Medium otherwise. Match the priority of the underlying component's +change. + +### E4_FORMAT_MODERNIZATION + +The asset's output structure is ad hoc, incomplete, or inconsistent with +current PromptKit format conventions — for example, it omits sections under +some conditions, lacks a "state 'None identified' rather than omit" rule, or +defines structure that an existing PromptKit format covers more completely. + +**Signals**: Free-form "report your findings" with no section contract; +sections that disappear when empty; no severity/confidence framework where one +applies; an output shape that duplicates an existing PromptKit format +(investigation-report, requirements-doc, structured-findings) less completely. + +**Example enhancement**: Replace "summarize what you found" with the +`investigation-report` format's section contract, including the "do not omit +sections" rule. + +**Priority guidance**: Medium. High when downstream tooling or a pipeline +consumes the output and depends on stable structure. + +### E5_DETERMINISM_HARDENING + +The asset contains language that introduces non-deterministic interpretation, +such that two different LLMs (or two runs) would produce materially different +structure or classifications. Apply the determinism checks from the +`self-verification` protocol (Rule 6) and the `prompt-determinism-analysis` +protocol. + +**Signals**: Vague quantifiers ("several", "some", "a few"); subjective +adjectives as criteria ("good", "clean", "appropriate"); conditionals with no +explicit else/default branch; standalone action verbs ("analyze", "evaluate") +without decomposed sub-steps; unbounded "keep it concise" with no limit. + +**Example enhancement**: Rewrite "review the most important functions" as +"review every function reachable from an exported entry point; if none are +exported, review every function." + +**Priority guidance**: Medium. High when the asset is reused across a team or +runs unattended, where drift compounds. + +### E6_PERSONA_EXPERTISE_GAP + +The asset lacks an explicit, task-appropriate expertise framing, or its +identity framing is thin or misaligned with the domain. A PromptKit persona +would supply the missing stance and domain knowledge. + +**Signals**: The asset opens directly with task steps and no "you are…" +identity; a generic "you are a helpful assistant" for a specialized task; an +identity whose domain does not match the task (e.g., a generic reviewer for +kernel code). + +**Example enhancement**: Prepend the `security-auditor` persona to a +vulnerability-hunting prompt that currently has no identity framing. + +**Priority guidance**: Medium. High when the task demands specialized domain +judgment (security, kernel, RF, firmware) that a generic identity would miss. + +### E7_STRUCTURAL_DECOMPOSITION + +The asset combines multiple concerns — identity, cross-cutting rules, output +structure, and task steps — in a single undifferentiated block, making it hard +to read, maintain, or reuse. Restructuring into clear PromptKit-style layers +(or, for agent/instruction assets, splitting into composable skill files) +improves clarity and reuse without changing intent. + +**Signals**: A long monolithic prompt with interleaved persona, rules, format, +and steps; a single instruction file covering many unrelated concerns that +`applyTo`-scoped skill files would target better; duplicated rules repeated +inline instead of referenced. + +**Example enhancement**: Split a 400-line "do everything" instruction file into +a persona skill (`applyTo: **`) plus a memory-safety skill +(`applyTo: **/*.c, **/*.h`). + +**Application note**: Splitting into multiple files is a file-level operation. +In action mode it requires explicit per-file confirmation before any file is +created, renamed, or deleted (see the `prompt-enhancement` protocol, Phase 6). + +**Priority guidance**: Low to Medium. Raise to Medium when the monolith is +actively edited by multiple people or reused across projects. + +### E8_PROVENANCE_STAMP + +The asset lacks a PromptKit provenance/version marker. Adding one records which +PromptKit version and components produced the current state, enabling future +`enhance-prompt` passes to detect prior provenance and apply E3 version +upgrades precisely. + +**Signals**: No `` marker; no record of which +components or version shaped the asset. + +**Example enhancement**: Add a provenance comment naming the PromptKit version +and the components applied during this enhancement pass. + +**Priority guidance**: Low. This is a forward-looking convenience, not a +capability gap. It ties to the low-priority output-versioning follow-up and +should never block higher-value enhancements. + +## Disambiguation and Precedence + +Each opportunity receives **exactly one** label. Because categories can overlap +(a missing guardrail is also, broadly, a "new capability"), apply the first +matching rule in this order and stop: + +1. **E3** — the gap is an older version of a specific PromptKit component the + asset already embodies, with provenance evidence (see E3). +2. **E1** — the gap is a missing cross-cutting guardrail (anti-hallucination, + self-verification, operational-constraints). +3. **E5** — the gap is vague or non-deterministic directive text to tighten. +4. **E6** — the gap is missing or misaligned persona/expertise framing. +5. **E4** — the gap is in the asset's output/report structure. +6. **E7** — the gap is monolithic structure better split into layers or files. +7. **E8** — the gap is a missing provenance/version marker. +8. **E2** — any other newly relevant PromptKit task- or domain-specific + capability (e.g., an analysis protocol or taxonomy) not covered above. + +The same precedence governs focus selection: choosing **E2** scopes the work to +new task/domain capabilities only; guardrails, determinism, persona, format, +decomposition, and provenance are requested via E1, E5, E6, E4, E7, and E8 +respectively. + +## Ranking Criteria + +Within a given priority level, order enhancements by value to the asset: + +1. **Highest value**: E1 (missing guardrail) and E3 (version upgrade) when the + underlying component addresses correctness or safety — these close active + capability gaps. +2. **High value**: E2 (new capability) for safety/security-relevant additions + and E5 (determinism hardening) for unattended or team-shared assets. +3. **Medium value**: E4 (format modernization), E6 (persona/expertise gap), + and remaining E2/E5 items. +4. **Lowest value**: E7 (structural decomposition) and E8 (provenance stamp) — + maintainability and forward-looking conveniences with no current capability + impact. + +## Usage + +In the enhancement plan and report, reference labels as: + +``` +[ENHANCE: E1_MISSING_GUARDRAIL] +Target: review-c.prompt.md (entire asset) +Opportunity: The prompt asks the model to "find and fix bugs" with no rule + against inventing function names or unverified behavior. +Source component: anti-hallucination (guardrail) +Priority: High +Status: Proposed +``` diff --git a/templates/enhance-prompt.md b/templates/enhance-prompt.md new file mode 100644 index 0000000..d57809a --- /dev/null +++ b/templates/enhance-prompt.md @@ -0,0 +1,191 @@ + + + +--- +name: enhance-prompt +mode: interactive +description: > + Enhance an existing prompt asset (raw prompt, Copilot prompt file, agent + definition, instruction/skill file, or a combination) with current PromptKit + capabilities. Detects PromptKit provenance, baselines current capabilities, + performs a gap analysis against the library, and proposes prioritized, + category-classified enhancements. Supports document mode (enhancement plan) + or action mode (apply in place after confirmation). Enables continuous + improvement of LLM prompt assets. +persona: promptkit-contributor +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - reasoning/prompt-enhancement +taxonomies: + - enhancement-categories +format: enhancement-report +params: + asset: "The prompt asset(s) to enhance — file path(s) or inline content. May be a raw prompt, Copilot prompt file, agent definition, instruction/skill file, or a combination." + focus: "Optional — one or more enhancement categories (numeric IDs E1–E8, or full label IDs like E1_MISSING_GUARDRAIL, from the enhancement-categories taxonomy) to scope the work. Leave blank to let PromptKit scan the asset and suggest categories." + output_mode: "Output mode — 'document' (produce an enhancement plan/report) or 'action' (apply confirmed enhancements in place)." + context: "Optional — how the asset is used, target runtime/platform, audience, and any constraints or regions to leave unchanged." +input_contract: null +output_contract: + type: enhancement-report + description: > + An enhancement report classifying each opportunity by the + enhancement-categories taxonomy, with provenance/version detection, a + prioritized plan, and — in action mode — the enhanced asset applied in + place. +--- + +# Task: Enhance Prompt Asset + +You are tasked with enhancing an existing **prompt asset** with current +PromptKit capabilities. A "prompt asset" is any LLM-facing instruction +artifact: a raw prompt, a Copilot prompt file (`.prompt.md`), an agent +definition, an instruction/skill file (e.g., `*.instructions.md`, `CLAUDE.md`, +`.cursorrules`), or a combination of these. + +The asset may or may not have been generated with PromptKit originally. If it +was, your goal includes **upgrading** it to incorporate capabilities that did +not exist when it was authored. If it was not, your goal is to **enrich** it +with relevant PromptKit capabilities. Either way, you **preserve the asset's +original intent and the user's customizations** — you enhance, you do not +rewrite. + +## Inputs + +**Asset(s) to enhance**: +{{asset}} + +**Focus** (optional enhancement categories): +{{focus}} + +**Output Mode**: +{{output_mode}} + +**Context**: +{{context}} + +## Instructions + +**Validate `output_mode` first.** It MUST be exactly `document` or `action`. +If `{{output_mode}}` is blank or any other value, ask the user which mode they +want before proceeding; never enter action mode (which writes to the asset) +without an explicit `action`. + +Apply the **prompt-enhancement protocol** end to end, and classify every +opportunity with the **enhancement-categories taxonomy**. Work interactively: +do not apply any change to the asset until the user confirms. + +### Phase 1: Ingest and Classify + +Execute prompt-enhancement Phase 1. Read every asset file in full, classify +each asset's type, state its intent (label `[KNOWN]` or `[INFERRED]`), and +record its structure and placeholders. If the intent cannot be determined from +the asset, ask the user before proceeding. + +### Phase 2: Detect Provenance and Version + +Execute prompt-enhancement Phase 2. Determine whether the asset was previously +shaped by PromptKit and, if so, its version. Treat a missing marker as a normal +result — never fabricate a version. Record the provenance classification for +the report's Provenance and Version Detection section. + +### Phase 3: Baseline and Gap Analysis + +1. Execute prompt-enhancement Phase 3 to inventory the asset's current + PromptKit-equivalent capabilities, recording coverage (Full / Partial / + Absent) and flagging user customizations to preserve. +2. Read `manifest.yaml`, then **read the candidate component files** it points + to (not just their manifest descriptions), and execute prompt-enhancement + Phase 4 to identify gaps. Classify each gap with exactly one + `enhancement-categories` label (E1–E8) using that taxonomy's Disambiguation + and Precedence rules, and distinguish E2 (new capability) from E3 (version + upgrade) strictly by the provenance evidence established in Phase 2. + +### Phase 4: Propose and Confirm + +Execute prompt-enhancement Phase 5. + +1. **Apply the focus**: if the user named focus categories in `{{focus}}`, + include only those categories in the actionable plan and record the rest as + residual. If `{{focus}}` is blank, present opportunities across all + categories and ask the user which to apply. +2. **Present the enhancement plan** using the `enhancement-report` format's + Enhancement Plan section (summary table + per-opportunity detail), ordered + by priority then by the taxonomy Ranking Criteria. Each opportunity starts + at status `Proposed`. +3. **Ask the user to confirm** which opportunities to act on. In **action + mode**, offer per opportunity: apply / defer / skip. In **document mode** + (no edits are written), offer: recommend (keep as `Proposed`) / defer / + skip. + + **Do NOT modify the asset until the user confirms.** + +### Phase 5: Output + +#### Document Mode (`output_mode: document`) + +Produce the `enhancement-report`. The Applied Changes section states +"Not applicable — document mode; no changes were written." All opportunities +carry status `Proposed`, `Deferred`, or `Skipped`. This report is the +deliverable; do not edit the asset. + +#### Action Mode (`output_mode: action`) + +1. Execute prompt-enhancement Phase 6 for each confirmed opportunity, one at a + time, in priority order. Preserve the asset's intent, customizations, native + format, and placeholder syntax. For any enhancement that creates, renames, + or deletes files (e.g., E7 structural decomposition), confirm the full + proposed file set per file before writing. Apply a provenance stamp (E8) + only if the user accepted it, and do it last. +2. Execute prompt-enhancement Phase 7 to verify coherence, intent preservation, + no regressions, and determinism of the additions. +3. Produce the `enhancement-report` recording each opportunity's final + status (`Applied` / `Deferred` / `Skipped`) and a per-file summary of + applied changes in the Applied Changes section. +4. **Never write changes the user did not confirm.** If the user confirmed + nothing, apply nothing and report all opportunities as `Proposed`, + `Deferred`, or `Skipped` as applicable. + +## Non-Goals + +- Do NOT rewrite the asset or change its task intent — enhance only. +- Do NOT remove or weaken existing capabilities or user customizations except + where the user explicitly approves a replacement (E3 version upgrade or E4 + format modernization). +- Do NOT invent PromptKit components or capabilities — propose only components + and conventions that exist in the current library (apply the + anti-hallucination protocol). +- Do NOT guess the asset's prior PromptKit version, and do NOT label a gap E3 + without provenance evidence tied to a specific component — treat such gaps as + new capabilities (E2) instead. +- Do NOT implement library-level output version-stamping here — that is a + separate, low-priority follow-up; this template only reads provenance markers + and may add one to the asset (E8) when accepted. +- Do NOT contribute the user's asset back to the PromptKit library — the output + belongs to the user. + +## Quality Checklist + +Before finalizing, verify: + +- [ ] Every asset file provided was read and classified (Phase 1) +- [ ] Provenance and version were determined, with a missing marker handled + gracefully and no fabricated version (Phase 2) +- [ ] Candidate library components were read (not just manifest descriptions) + before classifying gaps +- [ ] Every proposed enhancement carries exactly one enhancement-categories + label (via the taxonomy's Disambiguation and Precedence rules) and a + priority +- [ ] E3 (version upgrade) labels are used only with provenance evidence tied + to a specific component; otherwise gaps are labeled E2 +- [ ] The user's focus (if any) scoped the actionable plan; excluded + categories appear under Residual Gaps +- [ ] No change — including any file creation, rename, or deletion — was + applied without explicit user confirmation +- [ ] In action mode: the asset's intent, customizations, native format, and + placeholder syntax are preserved, and Phase 7 verification passed +- [ ] The enhancement-report sections are all present (none omitted; "None + identified" used where empty), including the Coverage section with + Examined / Method / Excluded / Limitations +- [ ] The report's E2/E3 classification is consistent with the recorded + provenance