From b0adb79e63d42cf109ffb4bc87d34803a74d8f1b Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:22:56 -0700 Subject: [PATCH 1/8] Add traceability audit template for cross-document specification drift MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new template that audits requirements, design, and validation documents for specification drift — gaps, contradictions, and divergence that accumulate as documents evolve independently. New components: - Persona: specification-analyst — adversarial toward completeness claims - Taxonomy: specification-drift (D1-D7) — classifies drift types with D8+ reserved for future code/test compliance audits - Protocol: traceability-audit — 6-phase cross-document comparison - Template: audit-traceability — single-shot, design doc optional Also extends the document-lifecycle pipeline with stage 4 (audit) and adds a use case section to README.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 36 ++++- manifest.yaml | 39 +++++ personas/specification-analyst.md | 64 ++++++++ protocols/reasoning/traceability-audit.md | 155 ++++++++++++++++++ taxonomies/specification-drift.md | 183 ++++++++++++++++++++++ templates/audit-traceability.md | 119 ++++++++++++++ 6 files changed, 593 insertions(+), 3 deletions(-) create mode 100644 personas/specification-analyst.md create mode 100644 protocols/reasoning/traceability-audit.md create mode 100644 taxonomies/specification-drift.md create mode 100644 templates/audit-traceability.md diff --git a/README.md b/README.md index 60e84fb..dc67622 100644 --- a/README.md +++ b/README.md @@ -198,13 +198,39 @@ prompt based on the user's needs. Templates declare **input and output contracts** so they can be chained: ``` -author-requirements-doc → author-design-doc → author-validation-plan - (produces: requirements) (consumes: requirements, (consumes: requirements, - produces: design) produces: validation) +author-requirements-doc → author-design-doc → author-validation-plan → audit-traceability + (produces: requirements) (consumes: requirements, (consumes: requirements, (consumes: all three, + produces: design) produces: validation) produces: drift report) ``` The output of one template becomes the input parameter of the next. +### Use Case: Specification Traceability Audit + +After authoring requirements, design, and validation documents — whether +through PromptKit's pipeline or by hand — you can audit all three for +**specification drift**: gaps, contradictions, and divergence that +accumulate as documents evolve independently. + +```bash +# Assemble a traceability audit prompt +npx @alan-jowett/promptkit assemble audit-traceability \ + -p project_name="Auth Service" \ + -p requirements_doc="$(cat requirements.md)" \ + -p design_doc="$(cat design.md)" \ + -p validation_plan="$(cat validation-plan.md)" \ + -o audit-report.md +``` + +The audit uses the `specification-drift` taxonomy (D1–D7) to classify +findings — untraced requirements, orphaned design decisions, assumption +drift, constraint violations, and illusory test coverage. Each finding +includes specific document locations, evidence, severity, and remediation +guidance. + +The design document is optional — omit it for a focused +requirements ↔ validation plan audit. + ## Components ### Personas @@ -214,6 +240,7 @@ The output of one template becomes the input parameter of the next. | `systems-engineer` | Memory management, concurrency, performance, debugging | | `security-auditor` | Vulnerability discovery, threat modeling, secure design | | `software-architect` | System design, API contracts, tradeoff analysis | +| `specification-analyst` | Cross-document traceability, coverage analysis, specification drift | ### Protocols @@ -240,6 +267,7 @@ The output of one template becomes the input parameter of the next. |------|-------------| | `root-cause-analysis` | Systematic root cause analysis | | `requirements-elicitation` | Requirements extraction from natural language | +| `traceability-audit` | Cross-document specification drift detection | ### Formats @@ -256,6 +284,7 @@ The output of one template becomes the input parameter of the next. | Name | Domain | Description | |------|--------|-------------| | `stack-lifetime-hazards` | Memory safety | H1–H5 labels for stack escape and lifetime violations | +| `specification-drift` | Specification traceability | D1–D7 labels for cross-document drift and divergence | ### Templates @@ -269,6 +298,7 @@ The output of one template becomes the input parameter of the next. | `review-code` | Code analysis | Code review for correctness and safety | | `plan-implementation` | Planning | Implementation task breakdown | | `plan-refactoring` | Planning | Safe, incremental refactoring plan | +| `audit-traceability` | Document auditing | Cross-document specification drift audit | ## Directory Structure diff --git a/manifest.yaml b/manifest.yaml index 9ce19f5..f5346cf 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -48,6 +48,13 @@ personas: behavioral requirements from existing implementations. Separates essential behavior from implementation details. + - name: specification-analyst + path: personas/specification-analyst.md + description: > + Senior specification analyst. Cross-examines requirements, design, + and validation artifacts for consistency, completeness, and + traceability. Adversarial toward completeness claims. + protocols: guardrails: - name: anti-hallucination @@ -137,6 +144,14 @@ protocols: from existing source code. Transforms code understanding into testable, atomic requirements with acceptance criteria. + - name: traceability-audit + path: protocols/reasoning/traceability-audit.md + description: > + Systematic cross-document comparison protocol for auditing + requirements, design, and validation artifacts. Builds + traceability matrices and classifies divergence using the + specification-drift taxonomy. + formats: - name: requirements-doc path: formats/requirements-doc.md @@ -230,6 +245,15 @@ taxonomies: hazards at system boundaries. Covers stack address escape, async pend/complete lifetime violations, and writable views of read-only data. + - name: specification-drift + path: taxonomies/specification-drift.md + domain: specification-traceability + description: > + Classification scheme (D1-D7) for specification drift across + requirements, design, and validation artifacts. Covers untraced + requirements, orphaned design decisions, assumption drift, and + acceptance criteria mismatch. Extensible to D8+ for code/test audits. + templates: document-authoring: - name: author-requirements-doc @@ -283,6 +307,18 @@ templates: protocols: [anti-hallucination, self-verification, operational-constraints, requirements-from-implementation] format: requirements-doc + - name: audit-traceability + path: templates/audit-traceability.md + description: > + Audit requirements, design, and validation documents for + specification drift. Cross-checks traceability, assumption + consistency, constraint propagation, and coverage completeness. + persona: specification-analyst + protocols: [anti-hallucination, self-verification, traceability-audit] + format: investigation-report + pipeline_position: 4 + requires: [requirements-document, validation-plan] + investigation: - name: investigate-bug path: templates/investigate-bug.md @@ -422,3 +458,6 @@ pipelines: - template: author-validation-plan consumes: requirements-document produces: validation-plan + - template: audit-traceability + consumes: [requirements-document, design-document, validation-plan] + produces: investigation-report diff --git a/personas/specification-analyst.md b/personas/specification-analyst.md new file mode 100644 index 0000000..3a5ea1d --- /dev/null +++ b/personas/specification-analyst.md @@ -0,0 +1,64 @@ + + + +--- +name: specification-analyst +description: > + Senior specification analyst. Cross-examines requirements, design, and + validation artifacts for consistency, completeness, and traceability. + Treats every coverage claim as unproven until evidence confirms it. +domain: + - specification analysis + - traceability and coverage analysis + - requirements verification + - document integrity auditing +tone: precise, skeptical, evidence-driven +--- + +# Persona: Senior Specification Analyst + +You are a senior specification analyst with deep experience auditing +software specifications for consistency and completeness across document +sets. Your expertise spans: + +- **Cross-document traceability**: Systematically tracing identifiers + (REQ-IDs, test case IDs, design references) across requirements, + design, and validation artifacts to verify complete, bidirectional + coverage. +- **Gap detection**: Finding what is absent — requirements with no + design realization, design decisions with no originating requirement, + test cases with no requirement linkage, acceptance criteria with no + corresponding test. +- **Assumption forensics**: Surfacing implicit assumptions in one document + that contradict, extend, or are absent from another. Assumptions that + cross document boundaries without explicit acknowledgment are findings. +- **Constraint verification**: Checking that constraints stated in + requirements are respected in design decisions and validated by test + cases — not just referenced, but actually addressed. +- **Drift detection**: Identifying where documents have diverged over time — + terminology shifts, scope changes reflected in one document but not + others, numbering inconsistencies, and orphaned references. + +## Behavioral Constraints + +- You treat every claim of coverage as **unproven until traced**. "The design + addresses all requirements" is not evidence — a mapping from each REQ-ID + to a specific design section is evidence. +- You are **adversarial toward completeness claims**. Your job is to find + what is missing, inconsistent, or unjustified — not to confirm that + documents are adequate. +- You work **systematically, not impressionistically**. You enumerate + identifiers, build matrices, and check cells — you do not skim + documents and report a general sense of alignment. +- You distinguish between **structural gaps** (a requirement has no test + case) and **semantic gaps** (a test case exists but does not actually + verify the requirement's acceptance criteria). Both are findings. +- When a document is absent (e.g., no design document provided), you + **restrict your analysis** to the documents available. You do not + fabricate what the missing document might contain. +- You report findings with **specific locations** — document, section, + identifier — not vague observations. Every finding must be traceable + to a concrete artifact. +- You do NOT assume that proximity implies traceability. A design section + that *mentions* a requirement keyword is not the same as a design + section that *addresses* a requirement. diff --git a/protocols/reasoning/traceability-audit.md b/protocols/reasoning/traceability-audit.md new file mode 100644 index 0000000..6541c13 --- /dev/null +++ b/protocols/reasoning/traceability-audit.md @@ -0,0 +1,155 @@ + + + +--- +name: traceability-audit +type: reasoning +description: > + Systematic cross-document comparison protocol for auditing requirements, + design, and validation artifacts. Builds traceability matrices, detects + gaps in both directions, and classifies divergence using the + specification-drift taxonomy. +applicable_to: + - audit-traceability +--- + +# Protocol: Traceability Audit + +Apply this protocol when auditing a set of specification documents +(requirements, design, validation plan) for consistency, completeness, +and traceability. The goal is to find every gap, conflict, and +unjustified assumption across the document set — not to confirm adequacy. + +## Phase 1: Artifact Inventory + +Before comparing documents, extract a complete inventory of traceable +items from each document provided. + +1. **Requirements document** — extract: + - Every REQ-ID (e.g., REQ-AUTH-001) with its category and summary + - Every acceptance criterion linked to each REQ-ID + - Every assumption (ASM-NNN) and constraint (CON-NNN) + - Every dependency (DEP-NNN) + - Defined terms and glossary entries + +2. **Design document** (if provided) — extract: + - Every component, interface, and module described + - Every explicit REQ-ID reference in design sections + - Every design decision and its stated rationale + - Every assumption stated or implied in the design + - Non-functional approach (performance strategy, security approach, etc.) + +3. **Validation plan** — extract: + - Every test case ID (TC-NNN) with its linked REQ-ID(s) + - The traceability matrix (REQ-ID → TC-NNN mappings) + - Test levels (unit, integration, system, etc.) + - Pass/fail criteria for each test case + - Environmental assumptions for test execution + +**Output**: A structured inventory for each document. If a document is +not provided, note its absence and skip its inventory — do NOT invent +content for the missing document. + +## Phase 2: Forward Traceability (Requirements → Downstream) + +Check that every requirement flows forward into downstream documents. + +1. **Requirements → Design** (skip if no design document): + - For each REQ-ID, search the design document for explicit references + or sections that address the requirement's specified behavior. + - A design section *mentioning* a requirement keyword is NOT sufficient. + The section must describe *how* the requirement is realized. + - Record: REQ-ID → design section(s), or mark as UNTRACED. + +2. **Requirements → Validation**: + - For each REQ-ID, check the traceability matrix for linked test cases. + - If the traceability matrix is absent or incomplete, search test case + descriptions for REQ-ID references. + - Record: REQ-ID → TC-NNN(s), or mark as UNTESTED. + +3. **Acceptance Criteria → Test Cases**: + - For each requirement that IS linked to a test case, verify that the + test case's steps and expected results actually exercise the + requirement's acceptance criteria. + - A test case that is *linked* but does not *verify* the acceptance + criteria is a D7_ACCEPTANCE_CRITERIA_MISMATCH. + +## Phase 3: Backward Traceability (Downstream → Requirements) + +Check that every item in downstream documents traces back to a requirement. + +1. **Design → Requirements** (skip if no design document): + - For each design component, interface, or major decision, identify + the originating requirement(s). + - Flag any design element that does not trace to a REQ-ID as a + candidate D3_ORPHANED_DESIGN_DECISION. + - Distinguish between: (a) genuine scope creep, (b) reasonable + architectural infrastructure (e.g., logging, monitoring) that + supports requirements indirectly, and (c) requirements gaps. + Report all three, but note the distinction. + +2. **Validation → Requirements**: + - For each test case (TC-NNN), verify it maps to a valid REQ-ID + that exists in the requirements document. + - Flag any test case with no REQ-ID mapping or with a reference + to a nonexistent REQ-ID as D4_ORPHANED_TEST_CASE. + +## Phase 4: Cross-Document Consistency + +Check that shared concepts, assumptions, and constraints are consistent +across all documents. + +1. **Assumption alignment**: + - Compare assumptions stated in the requirements document against + assumptions stated or implied in the design and validation plan. + - Flag contradictions, unstated assumptions, and extensions as + D5_ASSUMPTION_DRIFT. + +2. **Constraint propagation**: + - For each constraint in the requirements document, verify that: + - The design does not violate it (D6_CONSTRAINT_VIOLATION if it does). + - The validation plan includes tests that verify it. + - Pay special attention to non-functional constraints (performance, + scalability, security) which are often acknowledged in design but + not validated. + +3. **Terminology consistency**: + - Check that key terms are used consistently across documents. + - Flag cases where the same concept uses different names in different + documents, or where the same term means different things. + +4. **Scope alignment**: + - Compare the scope sections (or equivalent) across all documents. + - Flag items that are in scope in one document but out of scope + (or unmentioned) in another. + +## Phase 5: Classification and Reporting + +Classify every finding using the specification-drift taxonomy. + +1. Assign exactly one drift label (D1–D7) to each finding. +2. Assign severity using the taxonomy's severity guidance. +3. For each finding, provide: + - The drift label and short title + - The specific location in each relevant document (section, ID, line) + - Evidence (what is present, what is absent, what conflicts) + - Impact (what could go wrong if this drift is not resolved) + - Recommended resolution +4. Order findings by the taxonomy's ranking criteria (D6/D7 first, + then D2/D5, then D1/D3, then D4). + +## Phase 6: Coverage Summary + +After reporting individual findings, produce aggregate metrics: + +1. **Forward traceability rate**: % of REQ-IDs traced to design, + % traced to test cases. +2. **Backward traceability rate**: % of design elements traced to + requirements, % of test cases traced to requirements. +3. **Acceptance criteria coverage**: % of acceptance criteria with + corresponding test verification. +4. **Assumption consistency**: count of aligned vs. conflicting vs. + unstated assumptions. +5. **Overall assessment**: a summary judgment of specification integrity + (e.g., "High confidence — 2 minor gaps" or "Low confidence — + systemic traceability failures across all three documents"). diff --git a/taxonomies/specification-drift.md b/taxonomies/specification-drift.md new file mode 100644 index 0000000..5ef9fdc --- /dev/null +++ b/taxonomies/specification-drift.md @@ -0,0 +1,183 @@ + + + +--- +name: specification-drift +type: taxonomy +description: > + Classification scheme for specification drift and divergence across + requirements, design, and validation artifacts. Use when auditing + document sets for traceability gaps, scope creep, assumption drift, + and coverage failures. +domain: specification-traceability +applicable_to: + - audit-traceability +--- + +# Taxonomy: Specification Drift + +Use these labels to classify findings when auditing requirements, design, +and validation documents for consistency and completeness. Every finding +MUST use exactly one label from this taxonomy. + +## Labels + +### D1_UNTRACED_REQUIREMENT + +A requirement exists in the requirements document but is not referenced +or addressed in the design document. + +**Pattern**: REQ-ID appears in the requirements document. No section of +the design document references this REQ-ID or addresses its specified +behavior. + +**Risk**: The requirement may be silently dropped during implementation. +Without a design realization, there is no plan to deliver this capability. + +**Severity guidance**: High when the requirement is functional or +safety-critical. Medium when it is a non-functional or low-priority +constraint. + +### D2_UNTESTED_REQUIREMENT + +A requirement exists in the requirements document but has no +corresponding test case in the validation plan. + +**Pattern**: REQ-ID appears in the requirements document and may appear +in the traceability matrix, but no test case (TC-NNN) is linked to it — +or the traceability matrix entry is missing entirely. + +**Risk**: The requirement will not be verified. Defects against this +requirement will not be caught by the validation process. + +**Severity guidance**: Critical when the requirement is safety-critical +or security-related. High for functional requirements. Medium for +non-functional requirements with measurable criteria. + +### D3_ORPHANED_DESIGN_DECISION + +A design section, component, or decision does not trace back to any +requirement in the requirements document. + +**Pattern**: A design section describes a component, interface, or +architectural decision. No REQ-ID from the requirements document is +referenced or addressed by this section. + +**Risk**: Scope creep — the design introduces capabilities or complexity +not justified by the requirements. Alternatively, the requirements +document is incomplete and the design is addressing an unstated need. + +**Severity guidance**: Medium. Requires human judgment — the finding may +indicate scope creep (remove from design) or a requirements gap (add a +requirement). + +### D4_ORPHANED_TEST_CASE + +A test case in the validation plan does not map to any requirement in +the requirements document. + +**Pattern**: TC-NNN exists in the validation plan but references no +REQ-ID, or references a REQ-ID that does not exist in the requirements +document. + +**Risk**: Test effort is spent on behavior that is not required. +Alternatively, the requirements document is incomplete and the test +covers an unstated need. + +**Severity guidance**: Low to Medium. The test may still be valuable +(e.g., regression or exploratory), but it is not contributing to +requirements coverage. + +### D5_ASSUMPTION_DRIFT + +An assumption stated or implied in one document contradicts, extends, +or is absent from another document. + +**Pattern**: The design document states an assumption (e.g., "the system +will have at most 1000 concurrent users") that is not present in the +requirements document's assumptions section — or contradicts a stated +constraint. Similarly, the validation plan may assume environmental +conditions not specified in requirements. + +**Risk**: Documents are based on incompatible premises. Implementation +may satisfy the design's assumptions while violating the requirements' +constraints, or vice versa. + +**Severity guidance**: High when the assumption affects architectural +decisions or test validity. Medium when it affects non-critical behavior. + +### D6_CONSTRAINT_VIOLATION + +A design decision directly violates a stated requirement or constraint. + +**Pattern**: The requirements document states a constraint (e.g., +"the system MUST respond within 200ms") and the design document +describes an approach that cannot satisfy it (e.g., a synchronous +multi-service call chain with no caching), or explicitly contradicts +it (e.g., "response times up to 2 seconds are acceptable"). + +**Risk**: The implementation will not meet requirements by design. +This is not a gap but an active conflict. + +**Severity guidance**: Critical when the violated constraint is +safety-critical, regulatory, or a hard performance requirement. High +for functional constraints. + +### D7_ACCEPTANCE_CRITERIA_MISMATCH + +A test case is linked to a requirement but does not actually verify the +requirement's acceptance criteria. + +**Pattern**: TC-NNN is mapped to REQ-XXX-NNN in the traceability matrix, +but the test case's steps, inputs, or expected results do not correspond +to the acceptance criteria defined for that requirement. The test may +verify related but different behavior, or may be too coarse to confirm +the specific criterion. + +**Risk**: The traceability matrix shows coverage, but the coverage is +illusory. The requirement appears tested but its actual acceptance +criteria are not verified. + +**Severity guidance**: High. This is more dangerous than D2 (untested +requirement) because it creates a false sense of coverage. + +## Reserved Labels (Future Use) + +The following label ranges are reserved for future specification drift +categories involving implementation and test code: + +- **D8–D10**: Reserved for **code compliance** drift (requirements/design + vs. source code). Example: D8_UNIMPLEMENTED_REQUIREMENT — a requirement + has no corresponding implementation in source code. +- **D11–D13**: Reserved for **test compliance** drift (validation plan + vs. test code). Example: D11_UNIMPLEMENTED_TEST_CASE — a test case in + the validation plan has no corresponding automated test. + +These labels will be defined when the corresponding audit templates +(`audit-code-compliance`, `audit-test-compliance`) are added to the +library. + +## Ranking Criteria + +Order findings by impact on specification integrity: + +1. **Highest risk**: D6 (active constraint violation) and D7 (illusory + coverage) — these indicate the documents are actively misleading. +2. **High risk**: D2 (untested requirement) and D5 (assumption drift) — + these indicate silent gaps that will surface late. +3. **Medium risk**: D1 (untraced requirement) and D3 (orphaned design) — + these indicate incomplete traceability that needs human resolution. +4. **Lowest risk**: D4 (orphaned test case) — effort misdirection but + no safety or correctness impact. + +## Usage + +In findings, reference labels as: + +``` +[DRIFT: D2_UNTESTED_REQUIREMENT] +Requirement: REQ-SEC-003 (requirements doc, section 4.2) +Evidence: REQ-SEC-003 does not appear in the traceability matrix + (validation plan, section 4). No test case references this REQ-ID. +Impact: The encryption-at-rest requirement will not be verified. +``` diff --git a/templates/audit-traceability.md b/templates/audit-traceability.md new file mode 100644 index 0000000..6d3078e --- /dev/null +++ b/templates/audit-traceability.md @@ -0,0 +1,119 @@ + + + +--- +name: audit-traceability +description: > + Audit requirements, design, and validation documents for specification + drift. Cross-checks traceability, assumption consistency, constraint + propagation, and coverage completeness. Classifies findings using the + specification-drift taxonomy. +persona: specification-analyst +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - reasoning/traceability-audit +format: investigation-report +params: + project_name: "Name of the project or feature being audited" + requirements_doc: "The requirements document content" + design_doc: "The design document content (optional — omit for a two-document audit)" + validation_plan: "The validation plan content" + focus_areas: "Optional narrowing — e.g., 'security requirements only', 'API contracts' (default: audit all)" + audience: "Who will read the audit report — e.g., 'engineering leads', 'project stakeholders'" +input_contract: + type: requirements-document + description: > + A requirements document with numbered REQ-IDs and acceptance criteria. + A validation plan with test cases and traceability matrix. + Optionally, a design document with architecture and design decisions. +output_contract: + type: investigation-report + description: > + An investigation report classifying specification drift findings + using the D1–D7 taxonomy, with traceability matrices, coverage + metrics, and remediation recommendations. +--- + +# Task: Audit Specification Traceability + +You are tasked with auditing a set of specification documents for +**specification drift** — gaps, conflicts, and divergence between +requirements, design, and validation artifacts. + +## Inputs + +**Project Name**: {{project_name}} + +**Requirements Document**: +{{requirements_doc}} + +**Design Document** (if provided): +{{design_doc}} + +**Validation Plan**: +{{validation_plan}} + +**Focus Areas**: {{focus_areas}} + +## Instructions + +1. **Apply the traceability-audit protocol.** Execute all phases in order. + This is the core methodology — do not skip phases or take shortcuts. + +2. **Classify every finding** using the specification-drift taxonomy + (D1–D7). Every finding MUST have exactly one drift label, a severity, + specific locations in the source documents, evidence, and a + recommended resolution. + +3. **If the design document is not provided**, skip all design-related + checks (Phase 2 step 1, Phase 3 step 1, design-related consistency + checks in Phase 4). Restrict the audit to requirements ↔ validation + plan traceability. Do NOT fabricate or assume design content. + +4. **If focus areas are specified**, perform the full inventory (Phase 1) + but restrict detailed analysis (Phases 2–5) to requirements matching + the focus areas. Still report if the focus-area filter causes + significant portions of the document set to be excluded from audit. + +5. **Apply the anti-hallucination protocol.** Every finding must cite + specific identifiers and locations in the provided documents. Do NOT + invent requirements, test cases, or design sections that are not in + the inputs. If you infer a gap, label the inference explicitly. + +6. **Format the output** according to the investigation-report format. + Map the protocol's output to the report structure: + - Phase 1 inventory → Investigation Scope (section 3) + - Phases 2–4 findings → Findings (section 4), one F-NNN per drift item + - Phase 5 classification → Finding severity and categorization + - Phase 6 coverage summary → Executive Summary (section 1) and + a "Coverage Metrics" subsection in Root Cause Analysis (section 5) + - Recommended resolutions → Remediation Plan (section 6) + +7. **Quality checklist** — before finalizing, verify: + - [ ] Every REQ-ID from the requirements document appears in at least + one finding or is confirmed as fully traced + - [ ] Every finding has a specific drift label (D1–D7) + - [ ] Every finding cites specific document locations, not vague + references + - [ ] Severity assignments follow the taxonomy's guidance + - [ ] Findings are ordered by the taxonomy's ranking criteria + - [ ] Coverage metrics in the summary are calculated from actual + counts, not estimated + - [ ] If design document was absent, no findings reference design + content + - [ ] The executive summary is understandable without reading the + full report + +## Non-Goals + +- Do NOT modify or improve the input documents — report findings only. +- Do NOT generate missing requirements, design sections, or test cases — + identify and classify the gaps. +- Do NOT assess the quality of individual requirements, design decisions, + or test cases in isolation — focus on cross-document consistency. +- Do NOT evaluate whether the requirements are correct for the domain — + only whether the document set is internally consistent. +- Do NOT expand scope beyond the provided documents. External knowledge + about the domain may inform severity assessment but must not introduce + findings that are not evidenced in the documents. From 9afefe76882bdd6b3b9b76e4d885432522a5d6f9 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:43:07 -0700 Subject: [PATCH 2/8] Add specification integrity roadmap to docs/roadmap.md Document the phased evolution from cross-document spec audits (shipped) through bidirectional code/spec audits, invariant extraction, and standards/protocol analysis. Includes vision for continuous semantic integration as a CI consumer of PromptKit prompts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/roadmap.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/roadmap.md b/docs/roadmap.md index 4a90083..d7e2241 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -78,6 +78,91 @@ A lighter-weight option: a VS Code extension that provides: - One-click assembly with output to a new editor tab - Integration with VS Code's Copilot Chat via chat participants +## Specification Integrity & Drift Detection + +> **Status: Phase 1 shipped.** The traceability audit template and +> specification-drift taxonomy landed in PR #35. Phases 2–4 are planned. + +PromptKit is evolving toward a **specification integrity engine** — a +set of composable templates that detect gaps, contradictions, and drift +across the artifacts that define a software system: requirements, design, +validation plans, source code, and tests. + +### Phase 1: Cross-Document Specification Audits ✅ + +Shipped: `audit-traceability` template, `specification-analyst` persona, +`traceability-audit` protocol, and `specification-drift` taxonomy (D1–D7). + +Audits requirements, design, and validation documents for: +- Untraced requirements (D1) and untested requirements (D2) +- Orphaned design decisions (D3) and orphaned test cases (D4) +- Assumption drift (D5) and constraint violations (D6) +- Acceptance criteria mismatch (D7) — illusory test coverage + +The design document is optional, enabling two-document (requirements ↔ +validation) or three-document audits. Extends the `document-lifecycle` +pipeline as stage 4. + +### Phase 2: Bidirectional Code ↔ Spec Audits + +The specification-drift taxonomy reserves D8–D13 for these templates: + +- **`audit-code-compliance`** — Given requirements + design, audit source + code for unimplemented requirements, violated constraints, and + undocumented behavior. Answers: "Does the code implement what was + specified?" +- **`audit-test-compliance`** — Given requirements + validation plan, + audit test code for unimplemented test cases, missing assertions, and + coverage gaps. Answers: "Do the tests verify what the plan says they + should?" +- **Drift detection** — Surface spec-only behavior (specified but not + implemented), code-only behavior (implemented but not specified), and + mismatched assumptions between documents and code. + +These templates reuse the `specification-analyst` persona and extend the +`specification-drift` taxonomy. New protocols will handle the distinct +challenge of mapping document-level claims to code-level behavior. + +### Phase 3: Invariant Extraction + +- **Invariant extraction template** — Extract MUST/SHOULD/MAY constraints, + state transitions, timing assumptions, and error conditions from + existing specifications or code. Produces structured, machine-readable + invariant sets that can feed into audit templates. +- **Spec evolution diffing** — Compare two versions of the same + specification to detect breaking changes, relaxed constraints, and + shifted assumptions. Same pattern as traceability audit but applied + across time rather than across document types. + +### Phase 4: Standards & Protocol Analysis + +Applying the spec integrity methodology to formal standards (RFCs, IETF +protocols, API specifications): + +- **`standards-analyst` persona** — Domain expertise in normative language + (RFC 2119), protocol state machines, negotiation semantics, and + interoperability requirements. +- **RFC structural audits** — Internal consistency, normative language + correctness, state machine extraction, contradiction detection. +- **RFC → validation spec generation** — Convert MUST/SHOULD/MAY + requirements from RFCs into structured test conditions covering + negotiation, error handling, timing, and interoperability. +- **RFC ↔ implementation audits** — Audit reference implementations + against their governing RFCs for drift, undocumented capabilities, + and security mismatches. + +### Vision: Continuous Semantic Integration + +The long-term direction is enabling specification integrity checks as +part of continuous integration — every PR triggers doc ↔ code ↔ validation +audits, drift is caught at commit time, and specifications stay aligned +with implementation. + +This is an **integration concern** rather than a PromptKit template — the +component that runs audits in CI would be a separate tool that *uses* +PromptKit prompts. PromptKit's role is providing the composable audit +methodology; the CI integration consumes it. + ## New Templates Planned templates based on common engineering workflows: From 5c58c8df3f5fe8787c9287ed9ba878db0053fd18 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:43:40 -0700 Subject: [PATCH 3/8] Revert "Add specification integrity roadmap to docs/roadmap.md" This reverts commit 9afefe76882bdd6b3b9b76e4d885432522a5d6f9. --- docs/roadmap.md | 85 ------------------------------------------------- 1 file changed, 85 deletions(-) diff --git a/docs/roadmap.md b/docs/roadmap.md index d7e2241..4a90083 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -78,91 +78,6 @@ A lighter-weight option: a VS Code extension that provides: - One-click assembly with output to a new editor tab - Integration with VS Code's Copilot Chat via chat participants -## Specification Integrity & Drift Detection - -> **Status: Phase 1 shipped.** The traceability audit template and -> specification-drift taxonomy landed in PR #35. Phases 2–4 are planned. - -PromptKit is evolving toward a **specification integrity engine** — a -set of composable templates that detect gaps, contradictions, and drift -across the artifacts that define a software system: requirements, design, -validation plans, source code, and tests. - -### Phase 1: Cross-Document Specification Audits ✅ - -Shipped: `audit-traceability` template, `specification-analyst` persona, -`traceability-audit` protocol, and `specification-drift` taxonomy (D1–D7). - -Audits requirements, design, and validation documents for: -- Untraced requirements (D1) and untested requirements (D2) -- Orphaned design decisions (D3) and orphaned test cases (D4) -- Assumption drift (D5) and constraint violations (D6) -- Acceptance criteria mismatch (D7) — illusory test coverage - -The design document is optional, enabling two-document (requirements ↔ -validation) or three-document audits. Extends the `document-lifecycle` -pipeline as stage 4. - -### Phase 2: Bidirectional Code ↔ Spec Audits - -The specification-drift taxonomy reserves D8–D13 for these templates: - -- **`audit-code-compliance`** — Given requirements + design, audit source - code for unimplemented requirements, violated constraints, and - undocumented behavior. Answers: "Does the code implement what was - specified?" -- **`audit-test-compliance`** — Given requirements + validation plan, - audit test code for unimplemented test cases, missing assertions, and - coverage gaps. Answers: "Do the tests verify what the plan says they - should?" -- **Drift detection** — Surface spec-only behavior (specified but not - implemented), code-only behavior (implemented but not specified), and - mismatched assumptions between documents and code. - -These templates reuse the `specification-analyst` persona and extend the -`specification-drift` taxonomy. New protocols will handle the distinct -challenge of mapping document-level claims to code-level behavior. - -### Phase 3: Invariant Extraction - -- **Invariant extraction template** — Extract MUST/SHOULD/MAY constraints, - state transitions, timing assumptions, and error conditions from - existing specifications or code. Produces structured, machine-readable - invariant sets that can feed into audit templates. -- **Spec evolution diffing** — Compare two versions of the same - specification to detect breaking changes, relaxed constraints, and - shifted assumptions. Same pattern as traceability audit but applied - across time rather than across document types. - -### Phase 4: Standards & Protocol Analysis - -Applying the spec integrity methodology to formal standards (RFCs, IETF -protocols, API specifications): - -- **`standards-analyst` persona** — Domain expertise in normative language - (RFC 2119), protocol state machines, negotiation semantics, and - interoperability requirements. -- **RFC structural audits** — Internal consistency, normative language - correctness, state machine extraction, contradiction detection. -- **RFC → validation spec generation** — Convert MUST/SHOULD/MAY - requirements from RFCs into structured test conditions covering - negotiation, error handling, timing, and interoperability. -- **RFC ↔ implementation audits** — Audit reference implementations - against their governing RFCs for drift, undocumented capabilities, - and security mismatches. - -### Vision: Continuous Semantic Integration - -The long-term direction is enabling specification integrity checks as -part of continuous integration — every PR triggers doc ↔ code ↔ validation -audits, drift is caught at commit time, and specifications stay aligned -with implementation. - -This is an **integration concern** rather than a PromptKit template — the -component that runs audits in CI would be a separate tool that *uses* -PromptKit prompts. PromptKit's role is providing the composable audit -methodology; the CI integration consumes it. - ## New Templates Planned templates based on common engineering workflows: From 5aac7435d5c815747f6dd1678f0f48f33d7c2ce5 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:46:42 -0700 Subject: [PATCH 4/8] Add traceability audit case study Walks through an auth service example: three documents authored weeks apart, with accumulated drift (missing test coverage, scope creep, constraint violation, stale REQ-ID references). Shows before/after comparison and explains why each component contributes to the result. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/case-studies/audit-traceability.md | 193 ++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/case-studies/audit-traceability.md diff --git a/docs/case-studies/audit-traceability.md b/docs/case-studies/audit-traceability.md new file mode 100644 index 0000000..55b4a41 --- /dev/null +++ b/docs/case-studies/audit-traceability.md @@ -0,0 +1,193 @@ +# Case Study: Auditing Specification Drift with PromptKit + +## The Problem + +A team has written three specification documents for an authentication +service: a requirements document, a design document, and a validation +plan. The documents were authored at different times — requirements first, +then design a week later, then the validation plan two weeks after that. +During that time, the design introduced a session token refresh mechanism +that wasn't in the original requirements, and the validation plan was +written primarily from the design document rather than the requirements. + +Without PromptKit, a project lead reviews the three documents manually, +skimming for obvious gaps. They notice a few things seem off but can't +systematically identify every inconsistency. They sign off, and the team +starts implementation. Three sprints later, QA discovers that two +security requirements have no test cases, the session refresh feature was +never formally required, and a performance constraint in the requirements +is directly contradicted by the design's synchronous API call chain. + +## The PromptKit Approach + +### Assembling the Prompt + +```bash +npx promptkit assemble audit-traceability \ + -p project_name="Auth Service v2" \ + -p requirements_doc="$(cat auth-requirements.md)" \ + -p design_doc="$(cat auth-design.md)" \ + -p validation_plan="$(cat auth-validation.md)" \ + -p focus_areas="all" \ + -p audience="engineering leads and QA" \ + -o auth-traceability-audit.md +``` + +### What Gets Assembled + +The prompt composes four layers: + +**1. Identity — Specification Analyst Persona** + +The LLM adopts the identity of a senior specification analyst — +adversarial toward completeness claims, systematic rather than +impressionistic. Behavioral constraints include "treat every coverage +claim as unproven until traced" and "work by enumerating identifiers +and building matrices, not by skimming." + +**2. Reasoning Protocols** + +Three protocols are loaded: + +- **Anti-hallucination** — the LLM cannot invent requirements or test + cases that aren't in the documents. Every finding must cite specific + identifiers and locations. If the LLM infers a gap, it must label the + inference. +- **Self-verification** — before finalizing, the LLM verifies every + REQ-ID appears in at least one finding or is confirmed as traced, and + all coverage metrics are calculated from actual counts. +- **Traceability audit** — the 6-phase methodology: + 1. Artifact inventory (extract all IDs from each document) + 2. Forward traceability (requirements → design, requirements → validation) + 3. Backward traceability (design → requirements, validation → requirements) + 4. Cross-document consistency (assumptions, constraints, terminology) + 5. Classification using the specification-drift taxonomy (D1–D7) + 6. Coverage summary with aggregate metrics + +**3. Classification Taxonomy — Specification Drift** + +The D1–D7 taxonomy gives the LLM a precise vocabulary: + +| Label | Meaning | +|-------|---------| +| D1 | Requirement not traced to design | +| D2 | Requirement not traced to test case | +| D3 | Design decision with no originating requirement | +| D4 | Test case with no linked requirement | +| D5 | Assumption conflict across documents | +| D6 | Design violates a stated constraint | +| D7 | Test case doesn't verify its linked requirement's acceptance criteria | + +**4. Output Format — Investigation Report** + +Findings are structured as F-NNN entries with severity, evidence, +location, and remediation — the same format used for bug investigations +and security audits. + +## The Difference + +### Without PromptKit (manual review) + +A project lead reads through three documents, comparing them by memory. +They might catch obvious gaps — a section title that doesn't match, a +requirement they remember but can't find a test for. But they miss: + +- The two security requirements (REQ-SEC-003, REQ-SEC-007) buried in a + subsection with no test cases +- The session refresh feature that appeared in the design but was never + formally required +- The performance constraint (200ms response time) that the design's + synchronous multi-service call chain can't satisfy +- Three test cases referencing REQ-IDs that were renumbered in a + requirements revision + +### With PromptKit (composed audit) + +The LLM produces a structured investigation report: + +**Findings:** + +- **F-001 (Critical) [D6]:** Constraint violation. REQ-PERF-001 requires + 200ms response time. The design (section 5.3) specifies a synchronous + call chain: auth service → user store → token service → session cache. + At p95 latency, this chain exceeds 400ms. The design does not include + caching or async strategies to meet the constraint. + +- **F-002 (High) [D2]:** Untested requirement. REQ-SEC-003 (encryption + at rest for session tokens) does not appear in the traceability matrix. + No test case references this REQ-ID. The validation plan's security + section covers authentication but not token storage encryption. + +- **F-003 (High) [D2]:** Untested requirement. REQ-SEC-007 (token + revocation within 30 seconds) has no corresponding test case. The + validation plan tests token expiry but not revocation timing. + +- **F-004 (High) [D7]:** Acceptance criteria mismatch. TC-042 is linked + to REQ-AUTH-002 (multi-factor authentication). The test case verifies + that MFA is prompted but does not verify the acceptance criterion + "MUST reject single-factor authentication for admin roles." + +- **F-005 (Medium) [D3]:** Orphaned design decision. The session token + refresh mechanism (design section 4.7) is not traced to any + requirement. This may be scope creep, or the requirements document is + missing a requirement for session continuity. + +- **F-006 (Medium) [D5]:** Assumption drift. The design assumes a + maximum of 10,000 concurrent sessions (section 6.1). The requirements + document specifies 50,000 concurrent users (REQ-PERF-003) with no + stated session-to-user ratio. + +- **F-007 (Low) [D4]:** Orphaned test cases. TC-018, TC-019, and TC-020 + reference REQ-AUTH-010, REQ-AUTH-011, and REQ-AUTH-012 — none of which + exist in the current requirements document. These REQ-IDs appear to be + from a prior numbering scheme. + +**Coverage Summary:** + +| Metric | Value | +|--------|-------| +| Forward traceability (reqs → design) | 94% (2 of 32 untraced) | +| Forward traceability (reqs → validation) | 88% (4 of 32 untested) | +| Backward traceability (design → reqs) | 96% (1 of 24 orphaned) | +| Backward traceability (validation → reqs) | 95% (3 of 58 orphaned) | +| Assumption consistency | 1 conflict, 2 unstated | + +## Why It Works + +1. **The persona** sets the right mindset. The specification analyst + doesn't skim and approve — it systematically enumerates every ID and + checks every cell in the traceability matrix. The adversarial stance + means it actively looks for what's missing. + +2. **The traceability audit protocol** prevents shortcuts. The 6-phase + structure forces the LLM to build a complete inventory before drawing + conclusions. Forward AND backward traceability catches both missing + coverage and scope creep. + +3. **The specification-drift taxonomy** produces precise, actionable + findings. "D6: constraint violation" is more useful than "the design + might not meet performance requirements." The taxonomy also ranks + findings — D6 and D7 (active conflicts and illusory coverage) surface + before D4 (orphaned test cases). + +4. **Anti-hallucination** is critical here. Without it, the LLM might + invent a connection between a requirement and a design section because + they use similar words. The protocol forces the LLM to verify actual + ID references, not keyword proximity. + +## Takeaways + +- **Documents drift silently.** The three-week gap between authoring + requirements and validation was enough for scope creep, renumbered + IDs, and contradicted constraints to accumulate. +- **Manual review misses systematic gaps.** A human reviewer catches + "this doesn't look right" but not "REQ-SEC-003 has zero test cases." + The traceability matrix approach is exhaustive where skimming is not. +- **The design document is optional.** If the team only has requirements + and a validation plan, the audit still works — it restricts to + requirements ↔ validation traceability. This is useful earlier in the + lifecycle, before a design document exists. +- **Findings are actionable.** Each F-NNN has a specific resolution: + add a test case, add a requirement, fix a constraint violation, or + resolve an assumption conflict. The team can assign findings directly + to owners. From 9a7909d39ce387250e6f881b4fa1cbcb819a923f Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:50:58 -0700 Subject: [PATCH 5/8] Add scenarios gallery to docs Curated gallery of real-world scenarios showing when and why to use each template. Each scenario is a short paragraph: the problem, which components are assembled, and what you get. Covers 9 existing templates and 4 roadmap items. Bridges the gap between one-line descriptions in the README and full case study walkthroughs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/scenarios.md | 196 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 docs/scenarios.md diff --git a/docs/scenarios.md b/docs/scenarios.md new file mode 100644 index 0000000..9c4284c --- /dev/null +++ b/docs/scenarios.md @@ -0,0 +1,196 @@ +# PromptKit Scenarios + +Real-world situations where PromptKit turns a vague ask into a +structured, repeatable result. Each scenario shows the problem, +which components PromptKit assembles, and what you get. + +For full walkthroughs, see [case studies](case-studies/). + +--- + +## Existing Templates + +### "We keep finding bugs that the tests should have caught" + +Your validation plan says it covers all requirements, but two critical +security requirements have zero test cases and a third has a test that +checks the wrong thing. Nobody noticed because the traceability matrix +was built from memory, not verified. + +**Template:** `audit-traceability` · **Persona:** `specification-analyst` · +**Protocol:** `traceability-audit` · **Taxonomy:** `specification-drift` (D1–D7) + +**What you get:** An investigation report listing every requirement with +no test case (D2), every test case that doesn't actually verify its +linked acceptance criteria (D7), and coverage metrics showing exactly +where the validation plan has gaps. + +### "This crash only happens under load" + +A segfault in your C networking code appears at 100+ concurrent +connections but never in unit tests. The stack trace points to +`parse_header()` but the real problem is somewhere else. + +**Template:** `investigate-bug` · **Persona:** `systems-engineer` · +**Protocols:** `root-cause-analysis` + `memory-safety-c` + +**What you get:** A structured investigation report with ≥3 hypotheses +ranked by plausibility, evidence-based elimination, and a root-vs-proximate +cause distinction that prevents shallow fixes. The memory-safety protocol +catches lifetime issues the root cause analysis alone might miss. + +### "We need a requirements doc but the scope is fuzzy" + +The product manager gave you a half-page description of a new +authentication system. You need a real requirements document with +numbered REQ-IDs, acceptance criteria, and enough precision to hand +off to a design phase. + +**Template:** `interactive-design` · **Persona:** configurable · +**Protocols:** `requirements-elicitation` + `iterative-refinement` + +**What you get:** An interactive session that challenges your assumptions, +asks for quantified constraints ("what does 'fast' mean?"), identifies +implicit requirements you hadn't considered, and produces a structured +requirements document with stable identifiers. + +### "The design doesn't match what we agreed on" + +You wrote a requirements document last month. Now the design document +is done, but you suspect it drifted — new features crept in, a +performance constraint might be violated, and some requirements seem +to have been quietly dropped. + +**Template:** `audit-traceability` (without the validation plan) · +**Taxonomy:** `specification-drift` + +**What you get:** A two-document audit identifying orphaned design +decisions (D3), untraced requirements (D1), assumption drift (D5), +and constraint violations (D6). Each finding has specific document +locations and a recommended resolution. + +### "Review this PR for memory safety" + +A teammate submitted a C PR that touches buffer management code. You +want a thorough review that goes beyond style and catches real safety +issues. + +**Template:** `review-code` · **Persona:** `systems-engineer` · +**Protocols:** `memory-safety-c` + `thread-safety` + +**What you get:** An investigation report with severity-classified +findings covering allocation/deallocation pairing, pointer lifetime, +buffer boundaries, data races, and undefined behavior. Each finding +includes the code location, evidence, and a specific fix. + +### "We inherited a codebase with no documentation" + +A legacy C library has no spec, no design doc, and sparse comments. +You need to understand what it actually guarantees to its callers +before you can safely modify it. + +**Template:** `reverse-engineer-requirements` · **Persona:** `reverse-engineer` · +**Protocol:** `requirements-from-implementation` + +**What you get:** A structured requirements document extracted from the +code — API contracts, behavioral guarantees, error handling semantics, +and invariants — with each requirement labeled as KNOWN (directly +evidenced) or INFERRED (reasonable conclusion from patterns). + +### "Set up CI/CD for a new project" + +You need a GitHub Actions pipeline for a Python web app: lint, test, +build a Docker image, deploy to staging on PR merge, and deploy to +production on release tags. + +**Template:** `author-pipeline` · **Persona:** `devops-engineer` · +**Protocol:** `devops-platform-analysis` + +**What you get:** Production-ready YAML with design rationale, secret +and variable requirements, and a customization guide. Secure by default — +pinned action versions, least-privilege permissions, environment +protection rules. + +### "I want Copilot to always apply memory safety checks to C files" + +Instead of assembling a one-off prompt, you want the memory-safety +analysis baked into every Copilot session that touches C code in your +project. + +**Template:** `author-agent-instructions` · **Format:** `agent-instructions` + +**What you get:** A `.github/instructions/memory-safety-c.instructions.md` +file with `applyTo: "**/*.c, **/*.h"` that loads automatically in every +Copilot session touching C files. The systems-engineer persona and +memory-safety protocol become standing instructions. + +### "We have 47 open issues and no idea what to work on first" + +Your backlog has grown unwieldy. Some issues are duplicates, some are +stale, and the critical ones are buried under feature requests. + +**Template:** `triage-issues` · **Persona:** `devops-engineer` + +**What you get:** A prioritized triage report classifying every issue by +priority and effort, identifying patterns and duplicates, and +recommending a workflow for the next sprint. + +--- + +## Future Scenarios (Roadmap) + +These scenarios describe capabilities that are planned but not yet +implemented. See the [roadmap](roadmap.md) for details. + +### "Does the code actually implement what the spec says?" + +You have a requirements document and a design document. The code has +been written. But does it actually implement the specified behavior? +Are there requirements with no implementation? Features in the code +that nobody asked for? + +**Planned template:** `audit-code-compliance` · +**Taxonomy:** `specification-drift` (D8–D10) + +**What you'd get:** An investigation report listing unimplemented +requirements, code behavior not traced to any requirement, and +mismatched assumptions between the spec and the implementation. + +### "Do our tests actually test what the plan says they should?" + +Your validation plan specifies 58 test cases. Your test suite has +tests. But are they the same tests? Do the assertions match the +acceptance criteria? + +**Planned template:** `audit-test-compliance` · +**Taxonomy:** `specification-drift` (D11–D13) + +**What you'd get:** A report mapping validation plan test cases to +actual test implementations, identifying unimplemented test cases, +tests with wrong assertions, and coverage gaps between the plan and +reality. + +### "Extract the invariants from this RFC" + +You're implementing RFC 9110 (HTTP Semantics). You need to know every +MUST, SHOULD, and MAY — plus the state transitions, error conditions, +and timing constraints — as structured, testable requirements. + +**Planned template:** Invariant extraction · +**Planned persona:** `standards-analyst` + +**What you'd get:** A structured requirements document derived from the +RFC, with each normative statement extracted, classified by keyword +(MUST/SHOULD/MAY), and linked to the originating RFC section. + +### "Does our implementation match the RFC?" + +You've implemented a protocol. The RFC has been updated. Has your +implementation drifted? Are there MUST requirements you're violating? +Behaviors you implement that the RFC forbids? + +**Planned template:** RFC ↔ implementation audit + +**What you'd get:** A drift report between the RFC's normative +requirements and your implementation's actual behavior, with +security-sensitive mismatches flagged first. From dd3f2e377a918a17df29252d053e90dd0a72155b Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 18:58:02 -0700 Subject: [PATCH 6/8] Address review feedback: ordering, contracts, pipeline - Fix ordering conflict: use severity-first ordering with taxonomy ranking as tiebreaker within severity tiers (protocol, template, taxonomy) - Fix pipeline stage 4 consumes: remove optional design-document - Fix input_contract type: use validation-plan (matches pipeline stage) - Fix hyphen: cross document -> cross-document in persona Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cli/package-lock.json | 4 +- create_pptx.py | 536 ++++++++++++ create_pptx_deepdive.py | 980 ++++++++++++++++++++++ manifest.yaml | 2 +- personas/specification-analyst.md | 2 +- protocols/reasoning/traceability-audit.md | 5 +- taxonomies/specification-drift.md | 3 +- templates/audit-traceability.md | 11 +- 8 files changed, 1531 insertions(+), 12 deletions(-) create mode 100644 create_pptx.py create mode 100644 create_pptx_deepdive.py diff --git a/cli/package-lock.json b/cli/package-lock.json index 60270ea..89f560b 100644 --- a/cli/package-lock.json +++ b/cli/package-lock.json @@ -1,11 +1,11 @@ { - "name": "promptkit", + "name": "@alan-jowett/promptkit", "version": "0.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "promptkit", + "name": "@alan-jowett/promptkit", "version": "0.1.0", "license": "MIT", "dependencies": { diff --git a/create_pptx.py b/create_pptx.py new file mode 100644 index 0000000..203eafe --- /dev/null +++ b/create_pptx.py @@ -0,0 +1,536 @@ +"""Generate a PromptKit intro presentation (5–10 slides, engineering audience).""" + +from pptx import Presentation +from pptx.util import Inches, Pt, Emu +from pptx.dml.color import RGBColor +from pptx.enum.text import PP_ALIGN, MSO_ANCHOR +from pptx.enum.shapes import MSO_SHAPE + +# ── Theme colours ────────────────────────────────────────────── +BG = RGBColor(0x1E, 0x1E, 0x2E) # dark background +ACCENT = RGBColor(0x89, 0xB4, 0xFA) # soft blue +ACCENT2 = RGBColor(0xA6, 0xE3, 0xA1) # green +ACCENT3 = RGBColor(0xF9, 0xE2, 0xAF) # yellow/gold +WHITE = RGBColor(0xCD, 0xD6, 0xF4) # off-white text +DIM = RGBColor(0x6C, 0x70, 0x86) # muted text +SURFACE = RGBColor(0x31, 0x32, 0x44) # card/box bg +CODE_BG = RGBColor(0x18, 0x18, 0x25) # code block bg +ORANGE = RGBColor(0xFA, 0xB3, 0x87) + +W = Inches(13.333) # 16:9 +H = Inches(7.5) + +prs = Presentation() +prs.slide_width = W +prs.slide_height = H + +# ── helpers ──────────────────────────────────────────────────── +def dark_bg(slide): + bg = slide.background + fill = bg.fill + fill.solid() + fill.fore_color.rgb = BG + +def add_text(slide, left, top, width, height, text, *, + font_size=18, color=WHITE, bold=False, alignment=PP_ALIGN.LEFT, + font_name="Segoe UI", line_spacing=1.2): + txBox = slide.shapes.add_textbox(left, top, width, height) + tf = txBox.text_frame + tf.word_wrap = True + p = tf.paragraphs[0] + p.text = text + p.font.size = Pt(font_size) + p.font.color.rgb = color + p.font.bold = bold + p.font.name = font_name + p.alignment = alignment + p.space_after = Pt(font_size * 0.3) + if line_spacing != 1.0: + p.line_spacing = Pt(font_size * line_spacing) + return tf + +def add_para(tf, text, *, font_size=18, color=WHITE, bold=False, + font_name="Segoe UI", alignment=PP_ALIGN.LEFT, space_after=None, + line_spacing=None): + p = tf.add_paragraph() + p.text = text + p.font.size = Pt(font_size) + p.font.color.rgb = color + p.font.bold = bold + p.font.name = font_name + p.alignment = alignment + if space_after is not None: + p.space_after = Pt(space_after) + if line_spacing is not None: + p.line_spacing = Pt(line_spacing) + return p + +def add_rounded_rect(slide, left, top, width, height, fill_color=SURFACE): + shape = slide.shapes.add_shape( + MSO_SHAPE.ROUNDED_RECTANGLE, left, top, width, height) + shape.fill.solid() + shape.fill.fore_color.rgb = fill_color + shape.line.fill.background() + shape.shadow.inherit = False + return shape + +def add_accent_bar(slide, left, top, width=Inches(0.06), height=Inches(0.5), + color=ACCENT): + shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, width, height) + shape.fill.solid() + shape.fill.fore_color.rgb = color + shape.line.fill.background() + return shape + +def add_bullet_block(slide, left, top, width, bullets, *, + font_size=16, color=WHITE, bullet_color=ACCENT, + heading=None, heading_color=ACCENT): + h = Inches(0.4) if heading else Inches(0) + total_h = h + Inches(len(bullets) * 0.42) + tf = add_text(slide, left, top, width, total_h, + heading or bullets[0], + font_size=font_size + 2 if heading else font_size, + color=heading_color if heading else color, + bold=bool(heading)) + start = 0 if heading else 1 + for b in bullets[start:]: + add_para(tf, f" • {b}", font_size=font_size, color=color, + space_after=4, line_spacing=font_size * 1.3) + return tf + +def title_strip(slide, title, subtitle=None): + """Top accent bar + title across the slide.""" + # accent line + slide.shapes.add_shape( + MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), W, Inches(0.06) + ).fill.solid() + slide.shapes[-1].fill.fore_color.rgb = ACCENT + slide.shapes[-1].line.fill.background() + # title + add_text(slide, Inches(0.8), Inches(0.35), Inches(11), Inches(0.65), + title, font_size=32, color=WHITE, bold=True) + if subtitle: + add_text(slide, Inches(0.8), Inches(0.95), Inches(11), Inches(0.45), + subtitle, font_size=16, color=DIM) + +def speaker_notes(slide, text): + notes = slide.notes_slide + notes.notes_text_frame.text = text + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 1 — Title +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) # blank +dark_bg(s) + +# Large accent line +s.shapes.add_shape(MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), W, Inches(0.08) + ).fill.solid() +s.shapes[-1].fill.fore_color.rgb = ACCENT +s.shapes[-1].line.fill.background() + +# Logo +logo_size = Inches(2.5) +s.shapes.add_picture("PromptKit-logo.png", + Inches(0.9), Inches(1.2), logo_size, logo_size) + +# Title text — shifted right to sit beside the logo +add_text(s, Inches(3.7), Inches(1.6), Inches(9), Inches(1.2), + "PromptKit", font_size=64, color=WHITE, bold=True) +add_text(s, Inches(3.7), Inches(2.8), Inches(9), Inches(0.8), + "Composable, version-controlled prompts\nfor AI-assisted software engineering", + font_size=24, color=ACCENT) +add_text(s, Inches(3.7), Inches(4.1), Inches(9), Inches(0.5), + "github.com/microsoft/promptkit · MIT License · v0.1.0", + font_size=14, color=DIM) +add_text(s, Inches(0.9), Inches(6.2), Inches(11), Inches(0.4), + "Engineering Deep-Dive · Getting Started", + font_size=14, color=DIM) +speaker_notes(s, + "Welcome slide. PromptKit treats prompts as engineered software components — " + "composable, testable, version-controlled. Today we'll cover the architecture, " + "what's included, and how to start using it immediately.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 2 — The Problem +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Problem") + +problems = [ + ("Ad-hoc prompts", "Written once, pasted everywhere, never improved"), + ("No version control", "Can't track what changed, who changed it, or why"), + ("No reuse", "Every engineer reinvents the same persona / guardrails / format"), + ("No testing", "No way to verify prompt quality or catch regressions"), + ("Inconsistent outputs", "Same task → wildly different results across the team"), +] + +for i, (title, desc) in enumerate(problems): + y = Inches(1.65 + i * 1.0) + add_accent_bar(s, Inches(0.9), y, height=Inches(0.6), + color=[ORANGE, ACCENT3, ACCENT, ACCENT2, ACCENT][i]) + add_text(s, Inches(1.15), y - Inches(0.03), Inches(4), Inches(0.35), + title, font_size=20, color=WHITE, bold=True) + add_text(s, Inches(1.15), y + Inches(0.32), Inches(10), Inches(0.35), + desc, font_size=15, color=DIM) + +speaker_notes(s, + "Walk through each pain point. Most teams treat prompts as throwaway text. " + "But prompts are the primary interface to AI — they deserve the same engineering " + "rigor we apply to code: modularity, review, testing, reuse.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 3 — The Fix: Prompts as Code +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Fix: Treat Prompts as Code") + +pillars = [ + ("Modular", "Compose from reusable\nbuilding blocks", ACCENT), + ("Version-Controlled", "Track changes via\nGit like any code", ACCENT2), + ("Testable", "Reference-compare\nagainst known-good", ACCENT3), + ("Extensible", "Add your own personas,\nprotocols, templates", ORANGE), +] + +card_w = Inches(2.6) +gap = Inches(0.35) +total = len(pillars) * card_w.inches + (len(pillars) - 1) * gap.inches +start_x = (13.333 - total) / 2 + +for i, (title, desc, color) in enumerate(pillars): + x = Inches(start_x + i * (card_w.inches + gap.inches)) + y = Inches(2.2) + add_rounded_rect(s, x, y, card_w, Inches(2.8), SURFACE) + # color bar at top of card + s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, card_w, Inches(0.06) + ).fill.solid() + s.shapes[-1].fill.fore_color.rgb = color + s.shapes[-1].line.fill.background() + add_text(s, x + Inches(0.25), y + Inches(0.35), Inches(2.1), Inches(0.4), + title, font_size=20, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.25), y + Inches(0.95), Inches(2.1), Inches(1.2), + desc, font_size=15, color=WHITE, alignment=PP_ALIGN.CENTER) + +add_text(s, Inches(1.5), Inches(5.5), Inches(10), Inches(0.8), + "PromptKit applies the same engineering discipline you use for software\n" + "to the prompts that build it.", + font_size=16, color=DIM, alignment=PP_ALIGN.CENTER) + +speaker_notes(s, + "Four engineering principles applied to prompts. Modularity means you compose " + "from reusable layers instead of writing monolithic prompts. Version control means " + "prompts live in Git with full history. Testable means we have a reference-comparison " + "methodology. Extensible means the team can contribute new components via PR.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 4 — Architecture: The 5-Layer Stack +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Architecture: The 5-Layer Composition Stack") + +layers = [ + ("① Persona", "Who the LLM becomes", "systems-engineer, security-auditor, devops-engineer …", ACCENT), + ("② Protocols", "How it reasons + guardrails", "anti-hallucination, root-cause-analysis, thread-safety …", ACCENT2), + ("③ Format", "Output structure & rules", "requirements-doc, investigation-report, pipeline-spec …", ACCENT3), + ("④ Taxonomy", "Domain classification (optional)", "Severity levels, priority tiers, risk categories", ORANGE), + ("⑤ Template", "The task with parameters", "investigate-bug, review-code, author-design-doc …", RGBColor(0xF3, 0x8B, 0xA8)), +] + +for i, (name, role, examples, color) in enumerate(layers): + y = Inches(1.55 + i * 1.05) + # Layer bar + bar_w = Inches(11.5 - i * 0.6) + x = Inches((13.333 - bar_w.inches) / 2) + add_rounded_rect(s, x, y, bar_w, Inches(0.85), SURFACE) + # color accent on left + s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, Inches(0.07), Inches(0.85) + ).fill.solid() + s.shapes[-1].fill.fore_color.rgb = color + s.shapes[-1].line.fill.background() + # text + add_text(s, x + Inches(0.25), y + Inches(0.05), Inches(2.2), Inches(0.4), + name, font_size=18, color=color, bold=True) + add_text(s, x + Inches(2.5), y + Inches(0.05), Inches(3), Inches(0.4), + role, font_size=15, color=WHITE) + add_text(s, x + Inches(2.5), y + Inches(0.42), bar_w - Inches(2.7), Inches(0.4), + examples, font_size=12, color=DIM) + +add_text(s, Inches(1), Inches(6.9), Inches(11), Inches(0.4), + "Templates declare which components to compose via YAML frontmatter → bootstrap engine snaps them together", + font_size=13, color=DIM, alignment=PP_ALIGN.CENTER) + +speaker_notes(s, + "Walk through the stack bottom-up: Template is the task you want to accomplish. " + "It declares which persona, protocols, and format to use. The bootstrap engine " + "reads these declarations and assembles a single coherent prompt in this exact order. " + "The stacking/narrowing visual shows how each layer constrains the next.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 5 — What's In the Box +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "What's in the Box") + +categories = [ + ("6 Personas", [ + "systems-engineer", "security-auditor", + "software-architect", "devops-engineer", + "reverse-engineer", "spl-contributor" + ], ACCENT), + ("12 Protocols", [ + "Guardrails: anti-hallucination,\n self-verification, operational-constraints", + "Analysis: memory-safety-c, memory-safety-rust,\n thread-safety, security-vulnerability", + "Reasoning: root-cause-analysis,\n requirements-elicitation, iterative-refinement,\n devops-platform-analysis, requirements-from-impl" + ], ACCENT2), + ("9 Formats", [ + "requirements-doc, design-doc,\nvalidation-plan, investigation-report", + "implementation-plan, agent-instructions,\npipeline-spec, release-notes, multi-artifact" + ], ACCENT3), +] + +col_w = Inches(3.6) +gap = Inches(0.4) +total_w = len(categories) * col_w.inches + (len(categories) - 1) * gap.inches +sx = (13.333 - total_w) / 2 + +for i, (heading, items, color) in enumerate(categories): + x = Inches(sx + i * (col_w.inches + gap.inches)) + y = Inches(1.6) + add_rounded_rect(s, x, y, col_w, Inches(4.5), SURFACE) + # heading + add_text(s, x + Inches(0.2), y + Inches(0.15), col_w - Inches(0.4), Inches(0.4), + heading, font_size=22, color=color, bold=True, alignment=PP_ALIGN.CENTER) + # items + for j, item in enumerate(items): + lines = item.count('\n') + 1 + item_h = Inches(0.25 * lines + 0.15) + add_text(s, x + Inches(0.3), y + Inches(0.7 + j * (0.25 * lines + 0.35)), + col_w - Inches(0.6), item_h, + item, font_size=12, color=WHITE, font_name="Cascadia Code") + +# Bottom callout +add_rounded_rect(s, Inches(1), Inches(6.3), Inches(11.3), Inches(0.7), SURFACE) +add_text(s, Inches(1.3), Inches(6.35), Inches(10.7), Inches(0.6), + "19 Task Templates: investigate-bug · review-code · author-requirements-doc · " + "author-design-doc · plan-implementation · author-pipeline · triage-issues · " + "author-agent-instructions · extend-library … and more", + font_size=13, color=WHITE, alignment=PP_ALIGN.CENTER) + +speaker_notes(s, + "Inventory slide. Emphasize breadth: 6 domain-expert personas, 12 protocols across " + "3 categories (guardrails that prevent errors, analysis for domain-specific checks, " + "reasoning for systematic approaches), 9 output format specs, and 19 task templates. " + "All MIT-licensed, all composable.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 6 — Quick Start +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Quick Start — 3 Commands") + +commands = [ + ("Interactive mode", "npx @alan-jowett/promptkit", + "Detects your LLM CLI (Copilot / Claude) and\nlaunches an interactive prompt-building session", + ACCENT), + ("Browse templates", "npx @alan-jowett/promptkit list", + "Lists all available templates with descriptions\nAdd --json for machine-readable output", + ACCENT2), + ("Assemble a prompt", 'npx @alan-jowett/promptkit assemble investigate-bug \\\n' + ' -p problem_description="Segfault on startup" \\\n -o investigation.md', + "Composes persona + protocols + format + template\ninto a single ready-to-use prompt file", + ACCENT3), +] + +for i, (label, cmd, desc, color) in enumerate(commands): + y = Inches(1.6 + i * 1.8) + # label + add_text(s, Inches(0.9), y, Inches(3), Inches(0.35), + label, font_size=18, color=color, bold=True) + # code block + code_rect = add_rounded_rect(s, Inches(0.9), y + Inches(0.4), + Inches(7.5), Inches(0.9), CODE_BG) + add_text(s, Inches(1.1), y + Inches(0.45), Inches(7.1), Inches(0.8), + cmd, font_size=14, color=ACCENT2, font_name="Cascadia Code", + line_spacing=1.4) + # description + add_text(s, Inches(8.8), y + Inches(0.35), Inches(4), Inches(1.0), + desc, font_size=13, color=DIM) + +add_text(s, Inches(0.9), Inches(7.0), Inches(11), Inches(0.3), + "Prerequisites: Node.js 18+ · Optional: GitHub Copilot CLI or Claude Code for interactive mode", + font_size=12, color=DIM) + +speaker_notes(s, + "Live demo opportunity. Show each command in sequence. Interactive mode is the " + "flagship UX — it walks the user through component selection and parameter gathering. " + "The assemble command is for automation/scripting. List is for discovery.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 7 — Assembly Flow (visual) +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "How Assembly Works") + +steps = [ + ("Persona", "# Identity\nYou are a senior\nsystems engineer …", ACCENT), + ("Protocols", "# Reasoning\n## Anti-Hallucination\n## Root-Cause …", ACCENT2), + ("Format", "# Output Format\nInvestigation Report\nwith sections …", ACCENT3), + ("Template", "# Task\nInvestigate the bug:\n{{problem_description}}", ORANGE), +] + +box_w = Inches(2.5) +box_h = Inches(3.2) +arrow_w = Inches(0.6) +total_w = len(steps) * box_w.inches + (len(steps) - 1) * arrow_w.inches +sx = (13.333 - total_w) / 2 +y = Inches(1.8) + +for i, (label, content, color) in enumerate(steps): + x = Inches(sx + i * (box_w.inches + arrow_w.inches)) + add_rounded_rect(s, x, y, box_w, box_h, SURFACE) + # color top bar + s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, box_w, Inches(0.06) + ).fill.solid() + s.shapes[-1].fill.fore_color.rgb = color + s.shapes[-1].line.fill.background() + # label + add_text(s, x + Inches(0.15), y + Inches(0.2), box_w - Inches(0.3), Inches(0.35), + label, font_size=18, color=color, bold=True, alignment=PP_ALIGN.CENTER) + # content + add_text(s, x + Inches(0.15), y + Inches(0.7), box_w - Inches(0.3), Inches(2.2), + content, font_size=12, color=DIM, font_name="Cascadia Code", + alignment=PP_ALIGN.LEFT, line_spacing=1.5) + # arrow + if i < len(steps) - 1: + ax = x + box_w + Inches(0.1) + add_text(s, ax, y + Inches(1.2), arrow_w, Inches(0.5), + "→", font_size=28, color=DIM, alignment=PP_ALIGN.CENTER) + +# result box +result_y = Inches(5.4) +add_rounded_rect(s, Inches(2), result_y, Inches(9.3), Inches(1.2), CODE_BG) +add_text(s, Inches(2.3), result_y + Inches(0.1), Inches(8.7), Inches(1.0), + "Output: Single composed prompt file ─ ready to paste into any LLM\n" + "or use as agent instructions (.github/instructions/*.md, CLAUDE.md, .cursorrules)", + font_size=14, color=ACCENT, alignment=PP_ALIGN.CENTER, line_spacing=1.5) + +speaker_notes(s, + "Visual walkthrough of assembly. The engine reads the template's YAML frontmatter, " + "resolves each referenced component, and concatenates them in order. Parameters like " + "{{problem_description}} are substituted with user-provided values. The output is a " + "single markdown file that can be pasted into any LLM or saved as persistent agent instructions.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 8 — Pipeline Chaining +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Pipeline Chaining: Multi-Stage Workflows") + +pipeline_steps = [ + ("author-\nrequirements-doc", "requirements-\ndocument", ACCENT), + ("author-\ndesign-doc", "design-\ndocument", ACCENT2), + ("author-\nvalidation-plan", "validation-\nplan", ACCENT3), +] + +box_w = Inches(2.8) +box_h = Inches(2.5) +arrow_w = Inches(0.8) +total_w = len(pipeline_steps) * box_w.inches + (len(pipeline_steps) - 1) * arrow_w.inches +sx = (13.333 - total_w) / 2 +y = Inches(2.0) + +for i, (template, artifact, color) in enumerate(pipeline_steps): + x = Inches(sx + i * (box_w.inches + arrow_w.inches)) + add_rounded_rect(s, x, y, box_w, box_h, SURFACE) + s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, box_w, Inches(0.06) + ).fill.solid() + s.shapes[-1].fill.fore_color.rgb = color + s.shapes[-1].line.fill.background() + add_text(s, x + Inches(0.1), y + Inches(0.25), box_w - Inches(0.2), Inches(0.9), + template, font_size=16, color=WHITE, bold=True, + alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") + # produces label + add_text(s, x + Inches(0.1), y + Inches(1.35), box_w - Inches(0.2), Inches(0.3), + "produces ↓", font_size=12, color=DIM, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.1), y + Inches(1.7), box_w - Inches(0.2), Inches(0.7), + artifact, font_size=14, color=color, alignment=PP_ALIGN.CENTER, + font_name="Cascadia Code") + # arrow between boxes + if i < len(pipeline_steps) - 1: + ax = x + box_w + Inches(0.05) + add_text(s, ax, y + Inches(0.8), arrow_w, Inches(0.5), + "→", font_size=36, color=DIM, alignment=PP_ALIGN.CENTER) + +# explanation +add_text(s, Inches(1.5), Inches(5.0), Inches(10), Inches(1.5), + "Each template declares input/output contracts.\n" + "One template's artifact becomes the next template's input.\n" + "Build complete document lifecycles without copy-paste.", + font_size=16, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.6) + +speaker_notes(s, + "Pipeline chaining is the power feature. Templates declare input_contract and " + "output_contract with artifact types. The requirements doc feeds into design, " + "design feeds into validation planning. The bootstrap engine can suggest the " + "next stage automatically. This replaces ad-hoc copy-paste between tools.") + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 9 — Get Involved +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Get Started Today") + +actions = [ + ("Try it now", + "npx @alan-jowett/promptkit", + "Zero install — just run it. Walks you through\ntemplate selection and prompt assembly.", ACCENT), + ("Browse the repo", + "github.com/microsoft/promptkit", + "Read the templates, protocols, personas.\nUnderstand the composition model.", ACCENT2), + ("Contribute", + "Use the extend-library template", + "Add your own personas, protocols, or templates.\nPromptKit eats its own dog food — the contribution\nworkflow is itself a PromptKit template.", ACCENT3), + ("Share feedback", + "File issues or start discussions", + "What templates are missing? What workflows\ndo you wish PromptKit supported?", ORANGE), +] + +for i, (title, cmd, desc, color) in enumerate(actions): + y = Inches(1.55 + i * 1.35) + add_accent_bar(s, Inches(0.9), y, height=Inches(0.9), color=color) + add_text(s, Inches(1.2), y - Inches(0.02), Inches(4), Inches(0.35), + title, font_size=20, color=color, bold=True) + add_text(s, Inches(1.2), y + Inches(0.35), Inches(5), Inches(0.35), + cmd, font_size=14, color=WHITE, font_name="Cascadia Code") + add_text(s, Inches(7), y + Inches(0.05), Inches(5.5), Inches(0.8), + desc, font_size=13, color=DIM) + +speaker_notes(s, + "Call to action. The barrier to entry is one npx command. Encourage the team to " + "try it on a real task — bug investigation or code review works great as a first use. " + "The extend-library template is meta: you use PromptKit to contribute to PromptKit.") + + +# ════════════════════════════════════════════════════════════════ +# Save +# ════════════════════════════════════════════════════════════════ +out = "PromptKit-Intro-v2.pptx" +prs.save(out) +print(f"✅ Created {out}") diff --git a/create_pptx_deepdive.py b/create_pptx_deepdive.py new file mode 100644 index 0000000..6c6b92c --- /dev/null +++ b/create_pptx_deepdive.py @@ -0,0 +1,980 @@ +"""Generate a PromptKit deep-dive presentation (15-18 slides, engineering audience).""" + +from pptx import Presentation +from pptx.util import Inches, Pt, Emu +from pptx.dml.color import RGBColor +from pptx.enum.text import PP_ALIGN, MSO_ANCHOR +from pptx.enum.shapes import MSO_SHAPE + +# ── Theme colours ────────────────────────────────────────────── +BG = RGBColor(0x1E, 0x1E, 0x2E) +ACCENT = RGBColor(0x89, 0xB4, 0xFA) # blue +ACCENT2 = RGBColor(0xA6, 0xE3, 0xA1) # green +ACCENT3 = RGBColor(0xF9, 0xE2, 0xAF) # yellow +ORANGE = RGBColor(0xFA, 0xB3, 0x87) +PINK = RGBColor(0xF3, 0x8B, 0xA8) +MAUVE = RGBColor(0xCB, 0xA6, 0xF7) +WHITE = RGBColor(0xCD, 0xD6, 0xF4) +DIM = RGBColor(0x6C, 0x70, 0x86) +SURFACE = RGBColor(0x31, 0x32, 0x44) +CODE_BG = RGBColor(0x18, 0x18, 0x25) + +W = Inches(13.333) +H = Inches(7.5) + +prs = Presentation() +prs.slide_width = W +prs.slide_height = H + +# ── helpers ──────────────────────────────────────────────────── +def dark_bg(slide): + fill = slide.background.fill + fill.solid() + fill.fore_color.rgb = BG + +def add_text(slide, left, top, width, height, text, *, + font_size=18, color=WHITE, bold=False, alignment=PP_ALIGN.LEFT, + font_name="Segoe UI", line_spacing=1.2): + txBox = slide.shapes.add_textbox(left, top, width, height) + tf = txBox.text_frame + tf.word_wrap = True + p = tf.paragraphs[0] + p.text = text + p.font.size = Pt(font_size) + p.font.color.rgb = color + p.font.bold = bold + p.font.name = font_name + p.alignment = alignment + p.space_after = Pt(font_size * 0.3) + if line_spacing != 1.0: + p.line_spacing = Pt(font_size * line_spacing) + return tf + +def add_para(tf, text, *, font_size=18, color=WHITE, bold=False, + font_name="Segoe UI", alignment=PP_ALIGN.LEFT, space_after=None, + line_spacing=None): + p = tf.add_paragraph() + p.text = text + p.font.size = Pt(font_size) + p.font.color.rgb = color + p.font.bold = bold + p.font.name = font_name + p.alignment = alignment + if space_after is not None: + p.space_after = Pt(space_after) + if line_spacing is not None: + p.line_spacing = Pt(line_spacing) + return p + +def add_rounded_rect(slide, left, top, width, height, fill_color=SURFACE): + shape = slide.shapes.add_shape( + MSO_SHAPE.ROUNDED_RECTANGLE, left, top, width, height) + shape.fill.solid() + shape.fill.fore_color.rgb = fill_color + shape.line.fill.background() + shape.shadow.inherit = False + return shape + +def add_rect(slide, left, top, width, height, fill_color): + shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, width, height) + shape.fill.solid() + shape.fill.fore_color.rgb = fill_color + shape.line.fill.background() + return shape + +def title_strip(slide, title, subtitle=None): + add_rect(slide, Inches(0), Inches(0), W, Inches(0.06), ACCENT) + add_text(slide, Inches(0.8), Inches(0.35), Inches(11), Inches(0.65), + title, font_size=32, color=WHITE, bold=True) + if subtitle: + add_text(slide, Inches(0.8), Inches(0.95), Inches(11), Inches(0.45), + subtitle, font_size=16, color=DIM) + +def speaker_notes(slide, text): + slide.notes_slide.notes_text_frame.text = text + +def code_block(slide, left, top, width, height, text, *, font_size=12): + add_rounded_rect(slide, left, top, width, height, CODE_BG) + add_text(slide, left + Inches(0.2), top + Inches(0.1), + width - Inches(0.4), height - Inches(0.2), + text, font_size=font_size, color=ACCENT2, + font_name="Cascadia Code", line_spacing=1.5) + +def slide_number(slide, num, total): + add_text(slide, Inches(12.2), Inches(7.1), Inches(1), Inches(0.3), + f"{num} / {total}", font_size=10, color=DIM, + alignment=PP_ALIGN.RIGHT) + +TOTAL_SLIDES = 16 + +# ════════════════════════════════════════════════════════════════ +# SLIDE 1 — Title +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +add_rect(s, Inches(0), Inches(0), W, Inches(0.08), ACCENT) + +logo_size = Inches(2.5) +s.shapes.add_picture("PromptKit-logo.png", Inches(0.9), Inches(1.2), + logo_size, logo_size) + +add_text(s, Inches(3.7), Inches(1.6), Inches(9), Inches(1.2), + "PromptKit", font_size=64, color=WHITE, bold=True) +add_text(s, Inches(3.7), Inches(2.8), Inches(9), Inches(0.8), + "Composable, version-controlled prompts\nfor AI-assisted software engineering", + font_size=24, color=ACCENT) +add_text(s, Inches(3.7), Inches(4.1), Inches(9), Inches(0.5), + "github.com/microsoft/promptkit · MIT License · v0.1.0", + font_size=14, color=DIM) +add_text(s, Inches(0.9), Inches(6.2), Inches(11), Inches(0.4), + "Deep Dive · Architecture & Internals", + font_size=14, color=DIM) +speaker_notes(s, "Title slide. This is the deep-dive version covering architecture, " + "component internals, assembly engine, testing methodology, and pipeline chaining.") +slide_number(s, 1, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 2 — The Problem +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Problem with Ad-Hoc Prompts") + +problems = [ + ("Written once, pasted everywhere", "No iteration, no improvement loop, no review process", ORANGE), + ("No version control", "Can't diff, blame, or revert prompt changes", ACCENT3), + ("No reuse", "Every engineer reinvents persona, guardrails, output format", ACCENT), + ("No testing", "No way to verify quality or catch regressions", ACCENT2), + ("Inconsistent outputs", "Same task → wildly different results across the team", PINK), +] +for i, (title, desc, color) in enumerate(problems): + y = Inches(1.65 + i * 1.0) + add_rect(s, Inches(0.9), y, Inches(0.06), Inches(0.6), color) + add_text(s, Inches(1.15), y - Inches(0.03), Inches(4), Inches(0.35), + title, font_size=20, color=WHITE, bold=True) + add_text(s, Inches(1.15), y + Inches(0.32), Inches(10), Inches(0.35), + desc, font_size=15, color=DIM) +speaker_notes(s, "Walk through each pain point. The core insight: prompts are the " + "primary interface to AI tools, but we treat them as throwaway text.") +slide_number(s, 2, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 3 — The Fix +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Fix: Treat Prompts as Code") + +pillars = [ + ("Modular", "Compose from reusable\nbuilding blocks", ACCENT), + ("Version-\nControlled", "Track changes in Git\nlike any code", ACCENT2), + ("Testable", "Reference-compare\nagainst known-good", ACCENT3), + ("Extensible", "Add your own\ncomponents via PR", ORANGE), +] +card_w = Inches(2.6) +gap = Inches(0.35) +total = len(pillars) * card_w.inches + (len(pillars) - 1) * gap.inches +sx = (13.333 - total) / 2 +for i, (title, desc, color) in enumerate(pillars): + x = Inches(sx + i * (card_w.inches + gap.inches)) + y = Inches(2.0) + add_rounded_rect(s, x, y, card_w, Inches(2.5), SURFACE) + add_rect(s, x, y, card_w, Inches(0.06), color) + add_text(s, x + Inches(0.2), y + Inches(0.3), card_w - Inches(0.4), Inches(0.5), + title, font_size=20, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.2), y + Inches(1.0), card_w - Inches(0.4), Inches(1.2), + desc, font_size=15, color=WHITE, alignment=PP_ALIGN.CENTER) + +add_text(s, Inches(1.5), Inches(5.2), Inches(10), Inches(0.8), + "PromptKit applies the same engineering discipline you use for software\n" + "to the prompts that build it.", + font_size=16, color=DIM, alignment=PP_ALIGN.CENTER) +speaker_notes(s, "Four engineering principles. Modularity = compose layers. " + "Version control = full Git history. Testable = reference comparison methodology. " + "Extensible = anyone can contribute new components.") +slide_number(s, 3, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 4 — Architecture: 5-Layer Stack +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Architecture: The 5-Layer Composition Stack") + +layers = [ + ("① Persona", "Who the LLM becomes", "systems-engineer, security-auditor …", ACCENT), + ("② Protocols", "How it reasons + guardrails", "anti-hallucination, root-cause-analysis …", ACCENT2), + ("③ Format", "Output structure & rules", "investigation-report, design-doc …", ACCENT3), + ("④ Taxonomy", "Domain classification (opt.)", "severity tiers, risk categories", ORANGE), + ("⑤ Template", "The task with {{params}}", "investigate-bug, review-code …", PINK), +] +for i, (name, role, examples, color) in enumerate(layers): + y = Inches(1.55 + i * 1.05) + bar_w = Inches(11.5 - i * 0.6) + x = Inches((13.333 - bar_w.inches) / 2) + add_rounded_rect(s, x, y, bar_w, Inches(0.85), SURFACE) + add_rect(s, x, y, Inches(0.07), Inches(0.85), color) + add_text(s, x + Inches(0.25), y + Inches(0.05), Inches(2.2), Inches(0.4), + name, font_size=18, color=color, bold=True) + add_text(s, x + Inches(2.5), y + Inches(0.05), Inches(3), Inches(0.4), + role, font_size=15, color=WHITE) + add_text(s, x + Inches(2.5), y + Inches(0.42), bar_w - Inches(2.7), Inches(0.4), + examples, font_size=12, color=DIM) + +add_text(s, Inches(1), Inches(6.9), Inches(11), Inches(0.4), + "Templates declare which components to compose via YAML frontmatter → " + "the bootstrap engine snaps them together", + font_size=13, color=DIM, alignment=PP_ALIGN.CENTER) +speaker_notes(s, "The composition stack. Each layer constrains the next. Templates " + "declare their dependencies in YAML frontmatter — persona, protocols, format. " + "The narrowing visual shows how the stack funnels into a specific task.") +slide_number(s, 4, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 5 — Deep Dive: Personas +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Deep Dive: Personas", "Layer ① — Who the LLM becomes") + +# Left: YAML frontmatter example +code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(3.0), + "---\n" + "name: systems-engineer\n" + "description: >\n" + " Senior systems engineer with deep\n" + " expertise in memory management,\n" + " concurrency, and performance.\n" + "domain:\n" + " - systems programming\n" + " - debugging\n" + " - performance analysis\n" + "tone: precise, technical, methodical\n" + "---", font_size=13) + +# Right: behavioral constraints +add_text(s, Inches(6.8), Inches(1.5), Inches(5.5), Inches(0.35), + "Behavioral Constraints", font_size=20, color=ACCENT, bold=True) +constraints = [ + "Reason from first principles — trace causality, never guess", + "Distinguish epistemic states — label KNOWN / INFERRED / ASSUMED", + "Prefer correctness over cleverness", + "Explicit uncertainty — say what's missing", + "No hallucination — refuse to fabricate", +] +for i, c in enumerate(constraints): + add_text(s, Inches(6.8), Inches(2.1 + i * 0.55), Inches(5.8), Inches(0.5), + f" • {c}", font_size=13, color=WHITE) + +# Bottom: all personas +add_rounded_rect(s, Inches(0.8), Inches(5.2), Inches(11.7), Inches(1.6), SURFACE) +add_text(s, Inches(1.1), Inches(5.3), Inches(11), Inches(0.35), + "Available Personas", font_size=16, color=ACCENT3, bold=True) +personas = [ + ("systems-engineer", "Memory, concurrency, debugging"), + ("security-auditor", "Vulnerability discovery, threat modeling"), + ("software-architect", "System design, API contracts, tradeoffs"), + ("devops-engineer", "CI/CD, release engineering, IaC"), + ("reverse-engineer", "Spec extraction from existing code"), + ("spl-contributor", "Library architecture, conventions"), +] +for i, (name, desc) in enumerate(personas): + col = i % 3 + row = i // 3 + x = Inches(1.1 + col * 3.9) + y = Inches(5.75 + row * 0.5) + add_text(s, x, y, Inches(1.8), Inches(0.35), + name, font_size=11, color=ACCENT, bold=True, font_name="Cascadia Code") + add_text(s, x + Inches(1.85), y, Inches(2), Inches(0.35), + desc, font_size=11, color=DIM) + +speaker_notes(s, "Personas define identity, domain expertise, tone, and behavioral " + "constraints. The YAML frontmatter is machine-readable; the markdown body contains " + "the actual prompt content. Key: behavioral constraints reinforce the protocols.") +slide_number(s, 5, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 6 — Deep Dive: Protocols (3 categories) +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Deep Dive: Protocols", "Layer ② — How the LLM reasons") + +cats = [ + ("Guardrails", "Cross-cutting, apply to all tasks", [ + ("anti-hallucination", "Epistemic labeling, refusal\nto fabricate, source attribution"), + ("self-verification", "LLM verifies its own output\nbefore finalizing"), + ("operational-constraints", "Scoping, tool usage,\nreproducibility"), + ], ACCENT), + ("Analysis", "Domain/language-specific checks", [ + ("memory-safety-c", "Allocation, pointers, buffers"), + ("memory-safety-rust", "unsafe blocks, FFI, interior mut"), + ("thread-safety", "Races, deadlocks, atomics"), + ("security-vulnerability", "Trust boundaries, auth, crypto"), + ], ACCENT2), + ("Reasoning", "Systematic approaches", [ + ("root-cause-analysis", "Hypothesis → evidence →\nelimination → root cause"), + ("requirements-elicitation", "Atomic, testable REQ-IDs\nwith RFC 2119 keywords"), + ("iterative-refinement", "Structure-preserving\nfeedback cycles"), + ], ACCENT3), +] + +col_w = Inches(3.7) +gap_x = Inches(0.35) +total_w = len(cats) * col_w.inches + (len(cats) - 1) * gap_x.inches +sx = (13.333 - total_w) / 2 + +for ci, (cat_name, cat_desc, protocols, color) in enumerate(cats): + x = Inches(sx + ci * (col_w.inches + gap_x.inches)) + y = Inches(1.5) + card_h = Inches(5.5) + add_rounded_rect(s, x, y, col_w, card_h, SURFACE) + add_rect(s, x, y, col_w, Inches(0.06), color) + add_text(s, x + Inches(0.15), y + Inches(0.15), col_w - Inches(0.3), Inches(0.35), + cat_name, font_size=22, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.15), y + Inches(0.55), col_w - Inches(0.3), Inches(0.3), + cat_desc, font_size=11, color=DIM, alignment=PP_ALIGN.CENTER) + + for pi, (pname, pdesc) in enumerate(protocols): + py = y + Inches(1.05 + pi * 1.2) + add_rounded_rect(s, x + Inches(0.12), py, col_w - Inches(0.24), Inches(1.0), CODE_BG) + add_text(s, x + Inches(0.25), py + Inches(0.05), col_w - Inches(0.5), Inches(0.3), + pname, font_size=11, color=color, bold=True, font_name="Cascadia Code") + add_text(s, x + Inches(0.25), py + Inches(0.38), col_w - Inches(0.5), Inches(0.55), + pdesc, font_size=10, color=WHITE) + +speaker_notes(s, "Three protocol categories with different scoping rules. Guardrails are " + "cross-cutting (apply to every task). Analysis protocols are language/domain-specific. " + "Reasoning protocols define systematic methodologies. Separate files, not conditional blocks.") +slide_number(s, 6, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 7 — Anti-Hallucination Protocol (deep dive) +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Spotlight: Anti-Hallucination Protocol", + "The most important guardrail — prevents fabrication") + +rules = [ + ("Epistemic Labeling", + "Every claim tagged: KNOWN (directly stated), INFERRED (reasoned with " + "explicit chain), or ASSUMED (flagged with justification).\n" + "If ASSUMED > ~30% → stop and request more context.", + ACCENT), + ("Refusal to Fabricate", + "Do NOT invent function names, API signatures, config values, " + "file paths, or version numbers.\n" + 'Use [UNKNOWN: ] as placeholder.', + ORANGE), + ("Uncertainty Disclosure", + "Enumerate multiple interpretations rather than choosing silently. " + 'State: "Low confidence — depends on [assumption]. Verify by [action]."', + ACCENT3), + ("Source Attribution", + 'Indicate provenance: "per requirements doc §3.2" or "line 42 of auth.c".\n' + "Do NOT cite sources not provided.", + ACCENT2), + ("Scope Boundaries", + "If question falls outside provided context, say so explicitly.\n" + "List what additional information is needed.", + PINK), +] + +for i, (title, desc, color) in enumerate(rules): + y = Inches(1.5 + i * 1.12) + add_rect(s, Inches(0.8), y, Inches(0.06), Inches(0.85), color) + add_text(s, Inches(1.1), y - Inches(0.02), Inches(3), Inches(0.3), + title, font_size=18, color=color, bold=True) + add_text(s, Inches(4.0), y + Inches(0.02), Inches(8.5), Inches(0.85), + desc, font_size=12, color=WHITE, line_spacing=1.4) + +speaker_notes(s, "Deep dive into the anti-hallucination protocol. This is the single " + "most impactful guardrail. Epistemic labeling forces the LLM to be honest about " + "what it knows vs infers vs assumes. The 30% threshold prevents assumption-heavy outputs.") +slide_number(s, 7, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 8 — Root Cause Analysis Protocol +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Spotlight: Root Cause Analysis Protocol", + "5-phase structured reasoning methodology") + +phases = [ + ("Phase 1", "Symptom\nCharacterization", + "Observed vs expected, timeline,\nblast radius, deterministic?", ACCENT), + ("Phase 2", "Hypothesis\nGeneration", + "≥3 ranked hypotheses before\ninvestigating any. Include 1 non-obvious.", ACCENT2), + ("Phase 3", "Evidence &\nElimination", + "Minimal investigation per hypothesis.\nCONFIRMED / ELIMINATED / INCONCLUSIVE", ACCENT3), + ("Phase 4", "Root Cause\nIdentification", + "Distinguish root from proximate.\nTrace full causal chain.", ORANGE), + ("Phase 5", "Remediation", + "Fix root, not symptom.\nSecondary fixes + risk assessment.", PINK), +] + +box_w = Inches(2.1) +gap = Inches(0.3) +total_w = len(phases) * box_w.inches + (len(phases) - 1) * gap.inches +sx = (13.333 - total_w) / 2 +y = Inches(1.7) + +for i, (label, title, desc, color) in enumerate(phases): + x = Inches(sx + i * (box_w.inches + gap.inches)) + add_rounded_rect(s, x, y, box_w, Inches(3.5), SURFACE) + add_rect(s, x, y, box_w, Inches(0.06), color) + add_text(s, x + Inches(0.1), y + Inches(0.2), box_w - Inches(0.2), Inches(0.25), + label, font_size=11, color=DIM, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.1), y + Inches(0.5), box_w - Inches(0.2), Inches(0.7), + title, font_size=16, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.1), y + Inches(1.5), box_w - Inches(0.2), Inches(1.6), + desc, font_size=11, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.4) + if i < len(phases) - 1: + add_text(s, x + box_w + Inches(0.02), y + Inches(1.4), Inches(0.3), Inches(0.4), + "→", font_size=24, color=DIM, alignment=PP_ALIGN.CENTER) + +# Key insight callout +add_rounded_rect(s, Inches(1.5), Inches(5.6), Inches(10.3), Inches(1.2), CODE_BG) +add_text(s, Inches(1.8), Inches(5.7), Inches(9.7), Inches(1.0), + 'Key rule: "If we fix only the proximate cause, will the root cause\n' + 'produce other failures?" → If yes, the fix is incomplete.\n\n' + 'Example: Proximate = "null deref at line 42" · Root = "init silently fails when config missing"', + font_size=13, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.4) + +speaker_notes(s, "The RCA protocol enforces systematic debugging. The ≥3 hypothesis rule " + "prevents anchoring bias. The root vs proximate distinction is critical — most quick fixes " + "only address the proximate cause and leave the root cause to produce more bugs.") +slide_number(s, 8, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 9 — Deep Dive: Formats +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Deep Dive: Output Formats", "Layer ③ — Structured deliverables") + +# Left: format frontmatter +code_block(s, Inches(0.8), Inches(1.5), Inches(4.2), Inches(1.5), + "---\n" + "name: investigation-report\n" + "type: format\n" + "produces: investigation-report\n" + "---", font_size=13) + +# Left: section list +add_text(s, Inches(0.8), Inches(3.3), Inches(4.2), Inches(0.35), + "Investigation Report Structure", font_size=16, color=ACCENT, bold=True) +sections = [ + "1. Executive Summary (2-4 sentences)", + "2. Problem Statement", + "3. Investigation Scope + limitations", + "4. Findings (F-NNN, severity-ordered)", + "5. Root Cause Analysis (causal chain)", + "6. Remediation Plan (priority table)", + "7. Prevention (code + process + tooling)", + "8. Open Questions", + "9. Revision History", +] +for i, sec in enumerate(sections): + add_text(s, Inches(0.8), Inches(3.8 + i * 0.36), Inches(4.2), Inches(0.35), + sec, font_size=12, color=WHITE if i < 7 else DIM) + +# Right: all formats table +add_text(s, Inches(5.5), Inches(1.5), Inches(7), Inches(0.35), + "All Available Formats", font_size=18, color=ACCENT3, bold=True) +formats = [ + ("requirements-doc", "Numbered REQ-IDs + acceptance criteria", "requirements-document"), + ("design-doc", "Architecture, APIs, tradeoff analysis", "design-document"), + ("validation-plan", "Test cases + traceability matrix", "validation-plan"), + ("investigation-report", "Findings, RCA, remediation", "investigation-report"), + ("implementation-plan", "Task breakdown + dependencies", "implementation-plan"), + ("agent-instructions", ".github/instructions/, CLAUDE.md, .cursorrules", "agent-instructions"), + ("pipeline-spec", "YAML pipelines + design rationale", "pipeline-spec"), + ("release-notes", "Changelog, breaking changes, upgrade path", "release-notes"), + ("multi-artifact", "Multiple structured files", "multi-artifact"), +] + +# header +add_rounded_rect(s, Inches(5.5), Inches(2.0), Inches(7.3), Inches(0.4), ACCENT) +add_text(s, Inches(5.7), Inches(2.05), Inches(2.2), Inches(0.3), + "Format", font_size=12, color=BG, bold=True) +add_text(s, Inches(7.9), Inches(2.05), Inches(2.8), Inches(0.3), + "Produces", font_size=12, color=BG, bold=True) +add_text(s, Inches(10.7), Inches(2.05), Inches(2), Inches(0.3), + "Artifact Type", font_size=12, color=BG, bold=True) + +for i, (name, desc, artifact) in enumerate(formats): + y = Inches(2.5 + i * 0.48) + bg = SURFACE if i % 2 == 0 else CODE_BG + add_rounded_rect(s, Inches(5.5), y, Inches(7.3), Inches(0.42), bg) + add_text(s, Inches(5.7), y + Inches(0.05), Inches(2.1), Inches(0.3), + name, font_size=10, color=ACCENT, font_name="Cascadia Code") + add_text(s, Inches(7.9), y + Inches(0.05), Inches(2.7), Inches(0.3), + desc, font_size=10, color=WHITE) + add_text(s, Inches(10.7), y + Inches(0.05), Inches(2), Inches(0.3), + artifact, font_size=9, color=DIM, font_name="Cascadia Code") + +speaker_notes(s, "Formats define the output structure. The investigation-report format " + "has 9 sections with strict ordering rules. The 'produces' field enables pipeline " + "chaining — formats declare what artifact type they generate.") +slide_number(s, 9, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 10 — Deep Dive: Templates (frontmatter) +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Deep Dive: Template Anatomy", "Layer ⑤ — The task declaration") + +# Left: real frontmatter +code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(5.0), + "---\n" + "name: investigate-bug\n" + "description: >\n" + " Systematically investigate a bug.\n" + " Apply root cause analysis and produce\n" + " an investigation report.\n" + "\n" + "persona: systems-engineer\n" + "\n" + "protocols:\n" + " - guardrails/anti-hallucination\n" + " - guardrails/self-verification\n" + " - guardrails/operational-constraints\n" + " - reasoning/root-cause-analysis\n" + "\n" + "format: investigation-report\n" + "\n" + "params:\n" + " problem_description: \"Bug description\"\n" + " code_context: \"Relevant code/logs\"\n" + " environment: \"OS, runtime, build\"\n" + "\n" + "input_contract: null\n" + "output_contract:\n" + " type: investigation-report\n" + "---", font_size=12) + +# Right: field explanations +fields = [ + ("persona:", "References one persona file.\nBecomes the # Identity section.", ACCENT), + ("protocols:", "List of category/name paths.\nEach loaded as # Reasoning Protocol.", ACCENT2), + ("format:", "References one format file.\nBecomes the # Output Format section.", ACCENT3), + ("params:", "Key-value map → {{param}} placeholders\nin template body get substituted.", ORANGE), + ("input_contract:", "What artifact this template consumes.\nnull = no prerequisite.", PINK), + ("output_contract:", "What artifact this template produces.\nEnables pipeline chaining.", MAUVE), +] + +for i, (field, desc, color) in enumerate(fields): + y = Inches(1.5 + i * 0.9) + add_text(s, Inches(6.7), y, Inches(2.5), Inches(0.3), + field, font_size=15, color=color, bold=True, font_name="Cascadia Code") + add_text(s, Inches(6.7), y + Inches(0.32), Inches(6), Inches(0.55), + desc, font_size=12, color=WHITE, line_spacing=1.4) + +speaker_notes(s, "Template frontmatter is the composition declaration. The key insight: " + "protocols use category/name paths (guardrails/anti-hallucination) while the manifest " + "uses short names (anti-hallucination). CI validates they stay in sync.") +slide_number(s, 10, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 11 — The Manifest +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Manifest: Source of Truth", "manifest.yaml — the component registry") + +# Left: manifest structure +code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(5.2), + "# manifest.yaml\n" + "version: \"0.1.0\"\n" + "\n" + "personas:\n" + " - name: systems-engineer\n" + " path: personas/systems-engineer.md\n" + "\n" + "protocols:\n" + " guardrails:\n" + " - name: anti-hallucination\n" + " path: protocols/guardrails/...\n" + " analysis:\n" + " - name: memory-safety-c\n" + " path: protocols/analysis/...\n" + " reasoning:\n" + " - name: root-cause-analysis\n" + " path: protocols/reasoning/...\n" + "\n" + "formats:\n" + " - name: investigation-report\n" + " path: formats/investigation-report.md\n" + " produces: investigation-report\n" + "\n" + "templates:\n" + " investigation:\n" + " - name: investigate-bug\n" + " protocols: [anti-hallucination, ...]\n" # short names! + " format: investigation-report\n" + "\n" + "pipelines:\n" + " document-lifecycle:\n" + " stages:\n" + " - template: author-requirements-doc\n" + " produces: requirements-document", font_size=11) + +# Right: key rules +add_text(s, Inches(6.8), Inches(1.5), Inches(5.5), Inches(0.35), + "Key Rules", font_size=20, color=ACCENT, bold=True) + +rules = [ + ("Protocol naming duality", + "Templates use category paths:\n guardrails/anti-hallucination\n" + "Manifest uses short names:\n anti-hallucination\n" + "CI enforces they stay in sync.", ACCENT), + ("Path resolution", + "Every component has a path field\npointing to its .md source file.\n" + "Assembly engine reads these paths.", ACCENT2), + ("Pipeline stages", + "produces/consumes fields enable\nthe bootstrap engine to validate\n" + "chaining and suggest next stages.", ACCENT3), + ("CI validation", + "tests/validate-manifest.py checks\nthat manifest protocols match\n" + "template frontmatter protocols.", ORANGE), +] +for i, (title, desc, color) in enumerate(rules): + y = Inches(2.1 + i * 1.25) + add_rect(s, Inches(6.8), y, Inches(0.06), Inches(1.0), color) + add_text(s, Inches(7.05), y, Inches(5.5), Inches(0.3), + title, font_size=14, color=color, bold=True) + add_text(s, Inches(7.05), y + Inches(0.3), Inches(5.5), Inches(0.7), + desc, font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) + +speaker_notes(s, "The manifest is the component registry. Critical detail: protocols have " + "a naming duality — templates use category/name paths, manifest uses short names. " + "CI (validate-manifest.py) enforces sync. This is the only automated check in the repo.") +slide_number(s, 11, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 12 — Bootstrap Flow +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "The Bootstrap Flow", "bootstrap.md — the meta-prompt that drives composition") + +steps = [ + ("1", "Understand\nthe task", "Ask user what they\nwant to accomplish", ACCENT), + ("2", "Read\nmanifest", "Discover all available\ncomponents", ACCENT2), + ("3", "Select\ntemplate", "Match task to\nbest template", ACCENT3), + ("4", "Check\nmode", "Interactive → execute\nSingle-shot → file", ORANGE), + ("5", "Collect\nparams", "Gather template-\nspecific inputs", PINK), + ("6", "Assemble", "Compose layers\nin order", MAUVE), + ("7", "Output", "Write prompt file\nor execute directly", ACCENT), +] + +box_w = Inches(1.55) +box_h = Inches(2.5) +gap = Inches(0.15) +total_w = len(steps) * box_w.inches + (len(steps) - 1) * gap.inches +sx = (13.333 - total_w) / 2 + +for i, (num, title, desc, color) in enumerate(steps): + x = Inches(sx + i * (box_w.inches + gap.inches)) + y = Inches(1.7) + add_rounded_rect(s, x, y, box_w, box_h, SURFACE) + add_rect(s, x, y, box_w, Inches(0.05), color) + # number circle + add_text(s, x + Inches(0.05), y + Inches(0.15), box_w - Inches(0.1), Inches(0.3), + num, font_size=24, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.05), y + Inches(0.55), box_w - Inches(0.1), Inches(0.7), + title, font_size=14, color=WHITE, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.05), y + Inches(1.4), box_w - Inches(0.1), Inches(1.0), + desc, font_size=10, color=DIM, alignment=PP_ALIGN.CENTER, line_spacing=1.4) + if i < len(steps) - 1: + add_text(s, x + box_w - Inches(0.05), y + Inches(1.0), Inches(0.35), Inches(0.3), + "›", font_size=20, color=DIM, alignment=PP_ALIGN.CENTER) + +# Two modes callout +add_rounded_rect(s, Inches(0.8), Inches(4.6), Inches(5.7), Inches(2.3), CODE_BG) +add_text(s, Inches(1.0), Inches(4.7), Inches(5.3), Inches(0.3), + "Single-Shot Mode (default)", font_size=15, color=ACCENT, bold=True) +add_text(s, Inches(1.0), Inches(5.1), Inches(5.3), Inches(1.0), + "Gather params → assemble prompt → write .md file\n" + "User pastes into any LLM session\n\n" + "Output options:\n" + " (a) Raw prompt file\n" + " (b) Agent instructions (.github/instructions/,\n" + " CLAUDE.md, .cursorrules)", + font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) + +add_rounded_rect(s, Inches(6.8), Inches(4.6), Inches(5.7), Inches(2.3), CODE_BG) +add_text(s, Inches(7.0), Inches(4.7), Inches(5.3), Inches(0.3), + "Interactive Mode", font_size=15, color=ACCENT2, bold=True) +add_text(s, Inches(7.0), Inches(5.1), Inches(5.3), Inches(1.0), + "Load components → execute directly in session\n" + "Reasoning-and-challenge phase before output\n\n" + "Template declares: mode: interactive\n" + "Used by: extend-library, interactive-design\n" + "No file written — LLM acts on the prompt live", + font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) + +speaker_notes(s, "The bootstrap flow is the core UX. bootstrap.md is itself a meta-prompt — " + "it instructs the LLM how to use PromptKit. Two modes: single-shot writes a file you " + "paste elsewhere; interactive executes the prompt live in the current session.") +slide_number(s, 12, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 13 — Assembly Engine Internals +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Assembly Engine Internals", "cli/lib/assemble.js — how the sausage is made") + +# Assembly order diagram +order_items = [ + ("# Identity", "Load persona .md, strip frontmatter", ACCENT), + ("# Reasoning Protocols", "Load each protocol .md, join with ---", ACCENT2), + ("# Output Format", "Load format .md, strip frontmatter", ACCENT3), + ("# Task", "Load template .md, substitute {{params}}", ORANGE), +] + +for i, (section, desc, color) in enumerate(order_items): + y = Inches(1.6 + i * 1.15) + add_rounded_rect(s, Inches(0.8), y, Inches(5.5), Inches(0.95), SURFACE) + add_rect(s, Inches(0.8), y, Inches(0.07), Inches(0.95), color) + add_text(s, Inches(1.1), y + Inches(0.08), Inches(2.5), Inches(0.35), + section, font_size=16, color=color, bold=True, font_name="Cascadia Code") + add_text(s, Inches(1.1), y + Inches(0.48), Inches(4.8), Inches(0.4), + desc, font_size=13, color=WHITE) + if i < len(order_items) - 1: + add_text(s, Inches(3.3), y + Inches(0.95), Inches(1), Inches(0.3), + "↓", font_size=18, color=DIM, alignment=PP_ALIGN.CENTER) + +# Right: key functions +add_text(s, Inches(6.8), Inches(1.6), Inches(5.5), Inches(0.3), + "Key Processing Steps", font_size=18, color=ACCENT, bold=True) + +funcs = [ + ("stripFrontmatter()", + "Removes YAML --- block from\neach component before assembly", ACCENT), + ("Strip HTML comments", + "Removes SPDX license headers\n( blocks)", ACCENT2), + ("loadComponent()", + "Reads file, strips frontmatter +\ncomments, returns clean body", ACCENT3), + ("Parameter substitution", + "Simple {{key}} → value replacement\nvia split/join (no recursion)", ORANGE), + ("Section joining", + "Sections separated by markdown\nhorizontal rule (---)", PINK), +] + +for i, (name, desc, color) in enumerate(funcs): + y = Inches(2.1 + i * 0.95) + add_text(s, Inches(6.8), y, Inches(3), Inches(0.25), + name, font_size=13, color=color, bold=True, font_name="Cascadia Code") + add_text(s, Inches(6.8), y + Inches(0.28), Inches(5.5), Inches(0.55), + desc, font_size=11, color=WHITE, line_spacing=1.3) + +# Bottom: output +add_rounded_rect(s, Inches(0.8), Inches(6.2), Inches(11.7), Inches(0.8), CODE_BG) +add_text(s, Inches(1.1), Inches(6.3), Inches(11.1), Inches(0.6), + "Output: Single markdown string → # Identity\\n---\\n# Reasoning Protocols\\n---\\n" + "# Output Format\\n---\\n# Task", + font_size=12, color=ACCENT, alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") + +speaker_notes(s, "The assembly engine is deliberately simple. It reads the manifest to " + "resolve component paths, loads each .md file, strips YAML frontmatter and SPDX headers, " + "wraps in section headers, joins with horizontal rules, and substitutes parameters. " + "No template language, no recursion, no magic — just concatenation in a specific order.") +slide_number(s, 13, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 14 — Pipeline Chaining +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Pipeline Chaining: Multi-Stage Workflows", + "Templates connected by input/output contracts") + +pipeline_steps = [ + ("author-\nrequirements-doc", "requirements-\ndocument", ACCENT), + ("author-\ndesign-doc", "design-\ndocument", ACCENT2), + ("author-\nvalidation-plan", "validation-\nplan", ACCENT3), +] + +box_w = Inches(2.8) +box_h = Inches(2.5) +arrow_w = Inches(0.8) +total_w = len(pipeline_steps) * box_w.inches + (len(pipeline_steps) - 1) * arrow_w.inches +sx = (13.333 - total_w) / 2 +y = Inches(1.7) + +for i, (template, artifact, color) in enumerate(pipeline_steps): + x = Inches(sx + i * (box_w.inches + arrow_w.inches)) + add_rounded_rect(s, x, y, box_w, box_h, SURFACE) + add_rect(s, x, y, box_w, Inches(0.06), color) + add_text(s, x + Inches(0.1), y + Inches(0.25), box_w - Inches(0.2), Inches(0.9), + template, font_size=16, color=WHITE, bold=True, + alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") + add_text(s, x + Inches(0.1), y + Inches(1.35), box_w - Inches(0.2), Inches(0.3), + "produces ↓", font_size=12, color=DIM, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.1), y + Inches(1.7), box_w - Inches(0.2), Inches(0.7), + artifact, font_size=14, color=color, alignment=PP_ALIGN.CENTER, + font_name="Cascadia Code") + if i < len(pipeline_steps) - 1: + ax = x + box_w + Inches(0.05) + add_text(s, ax, y + Inches(0.8), arrow_w, Inches(0.5), + "→", font_size=36, color=DIM, alignment=PP_ALIGN.CENTER) + +# Contract mechanism +add_rounded_rect(s, Inches(0.8), Inches(4.6), Inches(11.7), Inches(2.4), CODE_BG) +add_text(s, Inches(1.1), Inches(4.7), Inches(5), Inches(0.3), + "How contracts work:", font_size=16, color=ACCENT, bold=True) + +contract_lines = [ + ("1.", "Template declares", "output_contract: { type: requirements-document }", ACCENT), + ("2.", "Next template declares", "input_contract: { type: requirements-document }", ACCENT2), + ("3.", "Manifest defines pipeline", "stages: [{produces: ...}, {consumes: ..., produces: ...}]", ACCENT3), + ("4.", "Bootstrap validates", "Previous output matches next input before offering template", ORANGE), + ("5.", "Artifacts flow forward", "Output of stage N becomes input parameter of stage N+1", PINK), +] + +for i, (num, label, detail, color) in enumerate(contract_lines): + y = Inches(5.15 + i * 0.35) + add_text(s, Inches(1.1), y, Inches(0.3), Inches(0.3), + num, font_size=12, color=color, bold=True) + add_text(s, Inches(1.4), y, Inches(2.3), Inches(0.3), + label, font_size=12, color=WHITE) + add_text(s, Inches(3.8), y, Inches(8.3), Inches(0.3), + detail, font_size=11, color=DIM, font_name="Cascadia Code") + +speaker_notes(s, "Pipeline chaining is the power feature. Templates declare input_contract " + "and output_contract with artifact types. The manifest defines pipeline stages. " + "The bootstrap engine validates contracts before offering the next template. " + "This replaces ad-hoc copy-paste between tools with a structured workflow.") +slide_number(s, 14, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 15 — Testing Methodology +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Testing: Reference Comparison Methodology", + "How do you test prompts? Compare against known-good references.") + +# Flow +flow_steps = [ + ("Hand-craft\nreference prompt", ACCENT), + ("Generate via\nPromptKit", ACCENT2), + ("Structured\ngap analysis", ACCENT3), + ("Feed gaps back\nas improvements", ORANGE), +] +box_w = Inches(2.5) +gap = Inches(0.5) +total_w = len(flow_steps) * box_w.inches + (len(flow_steps) - 1) * gap.inches +sx = (13.333 - total_w) / 2 + +for i, (label, color) in enumerate(flow_steps): + x = Inches(sx + i * (box_w.inches + gap.inches)) + add_rounded_rect(s, x, Inches(1.6), box_w, Inches(1.1), SURFACE) + add_rect(s, x, Inches(1.6), box_w, Inches(0.05), color) + add_text(s, x + Inches(0.1), Inches(1.75), box_w - Inches(0.2), Inches(0.8), + label, font_size=14, color=WHITE, bold=True, alignment=PP_ALIGN.CENTER) + if i < len(flow_steps) - 1: + add_text(s, x + box_w + Inches(0.08), Inches(1.9), Inches(0.4), Inches(0.4), + "→", font_size=24, color=DIM, alignment=PP_ALIGN.CENTER) + +# 5 dimensions +add_text(s, Inches(0.8), Inches(3.1), Inches(11), Inches(0.35), + "5 Gap Analysis Dimensions", font_size=20, color=ACCENT, bold=True) + +dimensions = [ + ("Task Framing", "Goal statement, success criteria,\nnon-goals, context definition", + "Is the objective clearly stated?\nIs scope explicitly bounded?", ACCENT), + ("Reasoning\nMethodology", "Systematic analysis, hypothesis\ngeneration, evidence requirements", + "Is anti-hallucination present?\nAre multiple hypotheses required?", ACCENT2), + ("Output\nSpecification", "Format structure, artifacts,\ntaxonomy, severity ranking", + "Is the deliverable structure defined?\nAre classification schemes provided?", ACCENT3), + ("Operational\nGuidance", "Scoping strategy, tool usage,\nstep-by-step plan", + "Does it guide how to scope work?\nIs a procedural plan provided?", ORANGE), + ("Quality\nAssurance", "Self-verification, sampling,\ncoverage, consistency", + "Must LLM verify its output?\nMust it document what it examined?", PINK), +] + +col_w = Inches(2.25) +gap_x = Inches(0.2) +total_w = len(dimensions) * col_w.inches + (len(dimensions) - 1) * gap_x.inches +sx = (13.333 - total_w) / 2 + +for i, (title, checks, questions, color) in enumerate(dimensions): + x = Inches(sx + i * (col_w.inches + gap_x.inches)) + add_rounded_rect(s, x, Inches(3.6), col_w, Inches(3.5), SURFACE) + add_rect(s, x, Inches(3.6), col_w, Inches(0.05), color) + add_text(s, x + Inches(0.1), Inches(3.75), col_w - Inches(0.2), Inches(0.55), + title, font_size=13, color=color, bold=True, alignment=PP_ALIGN.CENTER) + add_text(s, x + Inches(0.1), Inches(4.4), col_w - Inches(0.2), Inches(1.0), + checks, font_size=10, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.3) + add_text(s, x + Inches(0.1), Inches(5.5), col_w - Inches(0.2), Inches(1.2), + questions, font_size=9, color=DIM, alignment=PP_ALIGN.CENTER, line_spacing=1.3) + +speaker_notes(s, "Testing prompts is hard because output is non-deterministic. The reference " + "comparison methodology sidesteps this: compare prompt structure, not LLM output. " + "Each dimension gets ✅ Covered / ⚠️ Partial / ❌ Missing classification. " + "Gaps feed back into the library as improvements.") +slide_number(s, 15, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +# SLIDE 16 — Get Involved +# ════════════════════════════════════════════════════════════════ +s = prs.slides.add_slide(prs.slide_layouts[6]) +dark_bg(s) +title_strip(s, "Get Started Today") + +actions = [ + ("Try it now", + "npx @alan-jowett/promptkit", + "Zero install — walks you through template\nselection and prompt assembly.", ACCENT), + ("Browse the repo", + "github.com/microsoft/promptkit", + "Read the templates, protocols, personas.\nUnderstand the composition model.", ACCENT2), + ("Contribute", + "Use the extend-library template", + "PromptKit eats its own dog food — the\ncontribution workflow is a PromptKit template.", ACCENT3), + ("Share feedback", + "File issues or start discussions", + "What templates are missing? What workflows\ndo you wish PromptKit supported?", ORANGE), +] + +for i, (title, cmd, desc, color) in enumerate(actions): + y = Inches(1.55 + i * 1.35) + add_rect(s, Inches(0.9), y, Inches(0.06), Inches(0.9), color) + add_text(s, Inches(1.2), y - Inches(0.02), Inches(4), Inches(0.35), + title, font_size=20, color=color, bold=True) + add_text(s, Inches(1.2), y + Inches(0.35), Inches(5), Inches(0.35), + cmd, font_size=14, color=WHITE, font_name="Cascadia Code") + add_text(s, Inches(7), y + Inches(0.05), Inches(5.5), Inches(0.8), + desc, font_size=13, color=DIM) + +speaker_notes(s, "Call to action. The barrier to entry is one npx command. " + "The extend-library template is meta: you use PromptKit to contribute to PromptKit.") +slide_number(s, 16, TOTAL_SLIDES) + + +# ════════════════════════════════════════════════════════════════ +out = "PromptKit-DeepDive.pptx" +prs.save(out) +print(f"✅ Created {out} ({TOTAL_SLIDES} slides)") diff --git a/manifest.yaml b/manifest.yaml index f5346cf..c7528e7 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -459,5 +459,5 @@ pipelines: consumes: requirements-document produces: validation-plan - template: audit-traceability - consumes: [requirements-document, design-document, validation-plan] + consumes: [requirements-document, validation-plan] produces: investigation-report diff --git a/personas/specification-analyst.md b/personas/specification-analyst.md index 3a5ea1d..428f919 100644 --- a/personas/specification-analyst.md +++ b/personas/specification-analyst.md @@ -31,7 +31,7 @@ sets. Your expertise spans: corresponding test. - **Assumption forensics**: Surfacing implicit assumptions in one document that contradict, extend, or are absent from another. Assumptions that - cross document boundaries without explicit acknowledgment are findings. + cross-document boundaries without explicit acknowledgment are findings. - **Constraint verification**: Checking that constraints stated in requirements are respected in design decisions and validated by test cases — not just referenced, but actually addressed. diff --git a/protocols/reasoning/traceability-audit.md b/protocols/reasoning/traceability-audit.md index 6541c13..a26deca 100644 --- a/protocols/reasoning/traceability-audit.md +++ b/protocols/reasoning/traceability-audit.md @@ -135,8 +135,9 @@ Classify every finding using the specification-drift taxonomy. - Evidence (what is present, what is absent, what conflicts) - Impact (what could go wrong if this drift is not resolved) - Recommended resolution -4. Order findings by the taxonomy's ranking criteria (D6/D7 first, - then D2/D5, then D1/D3, then D4). +4. Order findings primarily by severity (Critical, then High, then + Medium, then Low). Within each severity tier, order by the taxonomy's + ranking criteria (D6/D7 first, then D2/D5, then D1/D3, then D4). ## Phase 6: Coverage Summary diff --git a/taxonomies/specification-drift.md b/taxonomies/specification-drift.md index 5ef9fdc..4f0f5d1 100644 --- a/taxonomies/specification-drift.md +++ b/taxonomies/specification-drift.md @@ -159,7 +159,8 @@ library. ## Ranking Criteria -Order findings by impact on specification integrity: +Within a given severity level, order findings by impact on specification +integrity: 1. **Highest risk**: D6 (active constraint violation) and D7 (illusory coverage) — these indicate the documents are actively misleading. diff --git a/templates/audit-traceability.md b/templates/audit-traceability.md index 6d3078e..147cf7d 100644 --- a/templates/audit-traceability.md +++ b/templates/audit-traceability.md @@ -22,11 +22,11 @@ params: focus_areas: "Optional narrowing — e.g., 'security requirements only', 'API contracts' (default: audit all)" audience: "Who will read the audit report — e.g., 'engineering leads', 'project stakeholders'" input_contract: - type: requirements-document + type: validation-plan description: > - A requirements document with numbered REQ-IDs and acceptance criteria. - A validation plan with test cases and traceability matrix. - Optionally, a design document with architecture and design decisions. + A validation plan with test cases and traceability matrix, plus the + requirements document it traces to. Optionally, a design document + with architecture and design decisions. output_contract: type: investigation-report description: > @@ -97,7 +97,8 @@ requirements, design, and validation artifacts. - [ ] Every finding cites specific document locations, not vague references - [ ] Severity assignments follow the taxonomy's guidance - - [ ] Findings are ordered by the taxonomy's ranking criteria + - [ ] Findings are ordered by severity (Critical → High → Medium → Low), + and within each severity level by the taxonomy's ranking criteria - [ ] Coverage metrics in the summary are calculated from actual counts, not estimated - [ ] If design document was absent, no findings reference design From f2e93fb8d6cd892a33ceeac35c0af23de1ff23d5 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 19:02:45 -0700 Subject: [PATCH 7/8] Add taxonomy support to CLI assembly The CLI assembler now includes taxonomies in assembled prompts, matching the bootstrap.md composition order (Identity -> Protocols -> Taxonomy -> Format -> Task). Templates declare taxonomies via a 'taxonomies' field in YAML frontmatter; the assembler resolves them from the manifest. This fixes the gap where taxonomy definitions (e.g., specification-drift D1-D7 labels) were not included when using 'promptkit assemble'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- cli/lib/assemble.js | 18 +++++++++++++++--- cli/lib/manifest.js | 15 ++++++++++++++- manifest.yaml | 1 + templates/audit-traceability.md | 2 ++ 4 files changed, 32 insertions(+), 4 deletions(-) diff --git a/cli/lib/assemble.js b/cli/lib/assemble.js index 1ecd167..b4d3dea 100644 --- a/cli/lib/assemble.js +++ b/cli/lib/assemble.js @@ -42,7 +42,7 @@ function substituteParams(content, params) { function assemble(contentDir, manifest, templateEntry, params = {}) { const { resolveTemplateDeps } = require("./manifest"); - const { persona, protocols, format } = resolveTemplateDeps( + const { persona, protocols, taxonomies, format } = resolveTemplateDeps( manifest, templateEntry ); @@ -69,7 +69,19 @@ function assemble(contentDir, manifest, templateEntry, params = {}) { } } - // 3. Output Format + // 3. Classification Taxonomy + if (taxonomies.length > 0) { + const taxonomyBodies = taxonomies + .map((t) => loadComponent(contentDir, t.path)) + .filter(Boolean); + if (taxonomyBodies.length > 0) { + sections.push( + "# Classification Taxonomy\n\n" + taxonomyBodies.join("\n\n---\n\n") + ); + } + } + + // 4. Output Format if (format) { const body = loadComponent(contentDir, format.path); if (body) { @@ -77,7 +89,7 @@ function assemble(contentDir, manifest, templateEntry, params = {}) { } } - // 4. Task (template) + // 5. Task (template) const templateBody = loadComponent(contentDir, templateEntry.path); if (templateBody) { sections.push("# Task\n\n" + templateBody); diff --git a/cli/lib/manifest.js b/cli/lib/manifest.js index ee4e23e..acdc562 100644 --- a/cli/lib/manifest.js +++ b/cli/lib/manifest.js @@ -39,6 +39,10 @@ function getFormat(manifest, name) { return (manifest.formats || []).find((f) => f.name === name); } +function getTaxonomy(manifest, name) { + return (manifest.taxonomies || []).find((t) => t.name === name); +} + function resolveTemplateDeps(manifest, template) { const persona = getPersona(manifest, template.persona); @@ -54,7 +58,15 @@ function resolveTemplateDeps(manifest, template) { const format = template.format ? getFormat(manifest, template.format) : null; - return { persona, protocols, format }; + const taxonomies = (template.taxonomies || []).map((name) => { + const tax = getTaxonomy(manifest, name); + if (!tax) { + console.warn(`Warning: taxonomy '${name}' not found in manifest`); + } + return tax; + }).filter(Boolean); + + return { persona, protocols, taxonomies, format }; } module.exports = { @@ -63,5 +75,6 @@ module.exports = { getPersona, getProtocol, getFormat, + getTaxonomy, resolveTemplateDeps, }; diff --git a/manifest.yaml b/manifest.yaml index c7528e7..7056aa3 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -315,6 +315,7 @@ templates: consistency, constraint propagation, and coverage completeness. persona: specification-analyst protocols: [anti-hallucination, self-verification, traceability-audit] + taxonomies: [specification-drift] format: investigation-report pipeline_position: 4 requires: [requirements-document, validation-plan] diff --git a/templates/audit-traceability.md b/templates/audit-traceability.md index 147cf7d..5a55446 100644 --- a/templates/audit-traceability.md +++ b/templates/audit-traceability.md @@ -13,6 +13,8 @@ protocols: - guardrails/anti-hallucination - guardrails/self-verification - reasoning/traceability-audit +taxonomies: + - specification-drift format: investigation-report params: project_name: "Name of the project or feature being audited" From ce0323af205081bc21efa41b646a09b999ad386a Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Thu, 19 Mar 2026 19:06:28 -0700 Subject: [PATCH 8/8] Fix review feedback round 2: diagram, package name, scenario, remove accidental files - Fix README pipeline diagram: design is optional, not 'all three' - Fix case study CLI command: use @alan-jowett/promptkit package name - Fix scenarios.md: correct the 'design drift' scenario to use all three docs (design is optional, not validation) - Remove accidentally committed create_pptx*.py files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 5 +- create_pptx.py | 536 ------------- create_pptx_deepdive.py | 980 ------------------------ docs/case-studies/audit-traceability.md | 2 +- docs/scenarios.md | 22 +- 5 files changed, 16 insertions(+), 1529 deletions(-) delete mode 100644 create_pptx.py delete mode 100644 create_pptx_deepdive.py diff --git a/README.md b/README.md index dc67622..6c84048 100644 --- a/README.md +++ b/README.md @@ -199,8 +199,9 @@ Templates declare **input and output contracts** so they can be chained: ``` author-requirements-doc → author-design-doc → author-validation-plan → audit-traceability - (produces: requirements) (consumes: requirements, (consumes: requirements, (consumes: all three, - produces: design) produces: validation) produces: drift report) + (produces: requirements) (consumes: requirements, (consumes: requirements, (consumes: requirements + + produces: design) produces: validation) validation; design optional, + produces: drift report) ``` The output of one template becomes the input parameter of the next. diff --git a/create_pptx.py b/create_pptx.py deleted file mode 100644 index 203eafe..0000000 --- a/create_pptx.py +++ /dev/null @@ -1,536 +0,0 @@ -"""Generate a PromptKit intro presentation (5–10 slides, engineering audience).""" - -from pptx import Presentation -from pptx.util import Inches, Pt, Emu -from pptx.dml.color import RGBColor -from pptx.enum.text import PP_ALIGN, MSO_ANCHOR -from pptx.enum.shapes import MSO_SHAPE - -# ── Theme colours ────────────────────────────────────────────── -BG = RGBColor(0x1E, 0x1E, 0x2E) # dark background -ACCENT = RGBColor(0x89, 0xB4, 0xFA) # soft blue -ACCENT2 = RGBColor(0xA6, 0xE3, 0xA1) # green -ACCENT3 = RGBColor(0xF9, 0xE2, 0xAF) # yellow/gold -WHITE = RGBColor(0xCD, 0xD6, 0xF4) # off-white text -DIM = RGBColor(0x6C, 0x70, 0x86) # muted text -SURFACE = RGBColor(0x31, 0x32, 0x44) # card/box bg -CODE_BG = RGBColor(0x18, 0x18, 0x25) # code block bg -ORANGE = RGBColor(0xFA, 0xB3, 0x87) - -W = Inches(13.333) # 16:9 -H = Inches(7.5) - -prs = Presentation() -prs.slide_width = W -prs.slide_height = H - -# ── helpers ──────────────────────────────────────────────────── -def dark_bg(slide): - bg = slide.background - fill = bg.fill - fill.solid() - fill.fore_color.rgb = BG - -def add_text(slide, left, top, width, height, text, *, - font_size=18, color=WHITE, bold=False, alignment=PP_ALIGN.LEFT, - font_name="Segoe UI", line_spacing=1.2): - txBox = slide.shapes.add_textbox(left, top, width, height) - tf = txBox.text_frame - tf.word_wrap = True - p = tf.paragraphs[0] - p.text = text - p.font.size = Pt(font_size) - p.font.color.rgb = color - p.font.bold = bold - p.font.name = font_name - p.alignment = alignment - p.space_after = Pt(font_size * 0.3) - if line_spacing != 1.0: - p.line_spacing = Pt(font_size * line_spacing) - return tf - -def add_para(tf, text, *, font_size=18, color=WHITE, bold=False, - font_name="Segoe UI", alignment=PP_ALIGN.LEFT, space_after=None, - line_spacing=None): - p = tf.add_paragraph() - p.text = text - p.font.size = Pt(font_size) - p.font.color.rgb = color - p.font.bold = bold - p.font.name = font_name - p.alignment = alignment - if space_after is not None: - p.space_after = Pt(space_after) - if line_spacing is not None: - p.line_spacing = Pt(line_spacing) - return p - -def add_rounded_rect(slide, left, top, width, height, fill_color=SURFACE): - shape = slide.shapes.add_shape( - MSO_SHAPE.ROUNDED_RECTANGLE, left, top, width, height) - shape.fill.solid() - shape.fill.fore_color.rgb = fill_color - shape.line.fill.background() - shape.shadow.inherit = False - return shape - -def add_accent_bar(slide, left, top, width=Inches(0.06), height=Inches(0.5), - color=ACCENT): - shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, width, height) - shape.fill.solid() - shape.fill.fore_color.rgb = color - shape.line.fill.background() - return shape - -def add_bullet_block(slide, left, top, width, bullets, *, - font_size=16, color=WHITE, bullet_color=ACCENT, - heading=None, heading_color=ACCENT): - h = Inches(0.4) if heading else Inches(0) - total_h = h + Inches(len(bullets) * 0.42) - tf = add_text(slide, left, top, width, total_h, - heading or bullets[0], - font_size=font_size + 2 if heading else font_size, - color=heading_color if heading else color, - bold=bool(heading)) - start = 0 if heading else 1 - for b in bullets[start:]: - add_para(tf, f" • {b}", font_size=font_size, color=color, - space_after=4, line_spacing=font_size * 1.3) - return tf - -def title_strip(slide, title, subtitle=None): - """Top accent bar + title across the slide.""" - # accent line - slide.shapes.add_shape( - MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), W, Inches(0.06) - ).fill.solid() - slide.shapes[-1].fill.fore_color.rgb = ACCENT - slide.shapes[-1].line.fill.background() - # title - add_text(slide, Inches(0.8), Inches(0.35), Inches(11), Inches(0.65), - title, font_size=32, color=WHITE, bold=True) - if subtitle: - add_text(slide, Inches(0.8), Inches(0.95), Inches(11), Inches(0.45), - subtitle, font_size=16, color=DIM) - -def speaker_notes(slide, text): - notes = slide.notes_slide - notes.notes_text_frame.text = text - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 1 — Title -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) # blank -dark_bg(s) - -# Large accent line -s.shapes.add_shape(MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), W, Inches(0.08) - ).fill.solid() -s.shapes[-1].fill.fore_color.rgb = ACCENT -s.shapes[-1].line.fill.background() - -# Logo -logo_size = Inches(2.5) -s.shapes.add_picture("PromptKit-logo.png", - Inches(0.9), Inches(1.2), logo_size, logo_size) - -# Title text — shifted right to sit beside the logo -add_text(s, Inches(3.7), Inches(1.6), Inches(9), Inches(1.2), - "PromptKit", font_size=64, color=WHITE, bold=True) -add_text(s, Inches(3.7), Inches(2.8), Inches(9), Inches(0.8), - "Composable, version-controlled prompts\nfor AI-assisted software engineering", - font_size=24, color=ACCENT) -add_text(s, Inches(3.7), Inches(4.1), Inches(9), Inches(0.5), - "github.com/microsoft/promptkit · MIT License · v0.1.0", - font_size=14, color=DIM) -add_text(s, Inches(0.9), Inches(6.2), Inches(11), Inches(0.4), - "Engineering Deep-Dive · Getting Started", - font_size=14, color=DIM) -speaker_notes(s, - "Welcome slide. PromptKit treats prompts as engineered software components — " - "composable, testable, version-controlled. Today we'll cover the architecture, " - "what's included, and how to start using it immediately.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 2 — The Problem -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Problem") - -problems = [ - ("Ad-hoc prompts", "Written once, pasted everywhere, never improved"), - ("No version control", "Can't track what changed, who changed it, or why"), - ("No reuse", "Every engineer reinvents the same persona / guardrails / format"), - ("No testing", "No way to verify prompt quality or catch regressions"), - ("Inconsistent outputs", "Same task → wildly different results across the team"), -] - -for i, (title, desc) in enumerate(problems): - y = Inches(1.65 + i * 1.0) - add_accent_bar(s, Inches(0.9), y, height=Inches(0.6), - color=[ORANGE, ACCENT3, ACCENT, ACCENT2, ACCENT][i]) - add_text(s, Inches(1.15), y - Inches(0.03), Inches(4), Inches(0.35), - title, font_size=20, color=WHITE, bold=True) - add_text(s, Inches(1.15), y + Inches(0.32), Inches(10), Inches(0.35), - desc, font_size=15, color=DIM) - -speaker_notes(s, - "Walk through each pain point. Most teams treat prompts as throwaway text. " - "But prompts are the primary interface to AI — they deserve the same engineering " - "rigor we apply to code: modularity, review, testing, reuse.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 3 — The Fix: Prompts as Code -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Fix: Treat Prompts as Code") - -pillars = [ - ("Modular", "Compose from reusable\nbuilding blocks", ACCENT), - ("Version-Controlled", "Track changes via\nGit like any code", ACCENT2), - ("Testable", "Reference-compare\nagainst known-good", ACCENT3), - ("Extensible", "Add your own personas,\nprotocols, templates", ORANGE), -] - -card_w = Inches(2.6) -gap = Inches(0.35) -total = len(pillars) * card_w.inches + (len(pillars) - 1) * gap.inches -start_x = (13.333 - total) / 2 - -for i, (title, desc, color) in enumerate(pillars): - x = Inches(start_x + i * (card_w.inches + gap.inches)) - y = Inches(2.2) - add_rounded_rect(s, x, y, card_w, Inches(2.8), SURFACE) - # color bar at top of card - s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, card_w, Inches(0.06) - ).fill.solid() - s.shapes[-1].fill.fore_color.rgb = color - s.shapes[-1].line.fill.background() - add_text(s, x + Inches(0.25), y + Inches(0.35), Inches(2.1), Inches(0.4), - title, font_size=20, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.25), y + Inches(0.95), Inches(2.1), Inches(1.2), - desc, font_size=15, color=WHITE, alignment=PP_ALIGN.CENTER) - -add_text(s, Inches(1.5), Inches(5.5), Inches(10), Inches(0.8), - "PromptKit applies the same engineering discipline you use for software\n" - "to the prompts that build it.", - font_size=16, color=DIM, alignment=PP_ALIGN.CENTER) - -speaker_notes(s, - "Four engineering principles applied to prompts. Modularity means you compose " - "from reusable layers instead of writing monolithic prompts. Version control means " - "prompts live in Git with full history. Testable means we have a reference-comparison " - "methodology. Extensible means the team can contribute new components via PR.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 4 — Architecture: The 5-Layer Stack -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Architecture: The 5-Layer Composition Stack") - -layers = [ - ("① Persona", "Who the LLM becomes", "systems-engineer, security-auditor, devops-engineer …", ACCENT), - ("② Protocols", "How it reasons + guardrails", "anti-hallucination, root-cause-analysis, thread-safety …", ACCENT2), - ("③ Format", "Output structure & rules", "requirements-doc, investigation-report, pipeline-spec …", ACCENT3), - ("④ Taxonomy", "Domain classification (optional)", "Severity levels, priority tiers, risk categories", ORANGE), - ("⑤ Template", "The task with parameters", "investigate-bug, review-code, author-design-doc …", RGBColor(0xF3, 0x8B, 0xA8)), -] - -for i, (name, role, examples, color) in enumerate(layers): - y = Inches(1.55 + i * 1.05) - # Layer bar - bar_w = Inches(11.5 - i * 0.6) - x = Inches((13.333 - bar_w.inches) / 2) - add_rounded_rect(s, x, y, bar_w, Inches(0.85), SURFACE) - # color accent on left - s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, Inches(0.07), Inches(0.85) - ).fill.solid() - s.shapes[-1].fill.fore_color.rgb = color - s.shapes[-1].line.fill.background() - # text - add_text(s, x + Inches(0.25), y + Inches(0.05), Inches(2.2), Inches(0.4), - name, font_size=18, color=color, bold=True) - add_text(s, x + Inches(2.5), y + Inches(0.05), Inches(3), Inches(0.4), - role, font_size=15, color=WHITE) - add_text(s, x + Inches(2.5), y + Inches(0.42), bar_w - Inches(2.7), Inches(0.4), - examples, font_size=12, color=DIM) - -add_text(s, Inches(1), Inches(6.9), Inches(11), Inches(0.4), - "Templates declare which components to compose via YAML frontmatter → bootstrap engine snaps them together", - font_size=13, color=DIM, alignment=PP_ALIGN.CENTER) - -speaker_notes(s, - "Walk through the stack bottom-up: Template is the task you want to accomplish. " - "It declares which persona, protocols, and format to use. The bootstrap engine " - "reads these declarations and assembles a single coherent prompt in this exact order. " - "The stacking/narrowing visual shows how each layer constrains the next.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 5 — What's In the Box -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "What's in the Box") - -categories = [ - ("6 Personas", [ - "systems-engineer", "security-auditor", - "software-architect", "devops-engineer", - "reverse-engineer", "spl-contributor" - ], ACCENT), - ("12 Protocols", [ - "Guardrails: anti-hallucination,\n self-verification, operational-constraints", - "Analysis: memory-safety-c, memory-safety-rust,\n thread-safety, security-vulnerability", - "Reasoning: root-cause-analysis,\n requirements-elicitation, iterative-refinement,\n devops-platform-analysis, requirements-from-impl" - ], ACCENT2), - ("9 Formats", [ - "requirements-doc, design-doc,\nvalidation-plan, investigation-report", - "implementation-plan, agent-instructions,\npipeline-spec, release-notes, multi-artifact" - ], ACCENT3), -] - -col_w = Inches(3.6) -gap = Inches(0.4) -total_w = len(categories) * col_w.inches + (len(categories) - 1) * gap.inches -sx = (13.333 - total_w) / 2 - -for i, (heading, items, color) in enumerate(categories): - x = Inches(sx + i * (col_w.inches + gap.inches)) - y = Inches(1.6) - add_rounded_rect(s, x, y, col_w, Inches(4.5), SURFACE) - # heading - add_text(s, x + Inches(0.2), y + Inches(0.15), col_w - Inches(0.4), Inches(0.4), - heading, font_size=22, color=color, bold=True, alignment=PP_ALIGN.CENTER) - # items - for j, item in enumerate(items): - lines = item.count('\n') + 1 - item_h = Inches(0.25 * lines + 0.15) - add_text(s, x + Inches(0.3), y + Inches(0.7 + j * (0.25 * lines + 0.35)), - col_w - Inches(0.6), item_h, - item, font_size=12, color=WHITE, font_name="Cascadia Code") - -# Bottom callout -add_rounded_rect(s, Inches(1), Inches(6.3), Inches(11.3), Inches(0.7), SURFACE) -add_text(s, Inches(1.3), Inches(6.35), Inches(10.7), Inches(0.6), - "19 Task Templates: investigate-bug · review-code · author-requirements-doc · " - "author-design-doc · plan-implementation · author-pipeline · triage-issues · " - "author-agent-instructions · extend-library … and more", - font_size=13, color=WHITE, alignment=PP_ALIGN.CENTER) - -speaker_notes(s, - "Inventory slide. Emphasize breadth: 6 domain-expert personas, 12 protocols across " - "3 categories (guardrails that prevent errors, analysis for domain-specific checks, " - "reasoning for systematic approaches), 9 output format specs, and 19 task templates. " - "All MIT-licensed, all composable.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 6 — Quick Start -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Quick Start — 3 Commands") - -commands = [ - ("Interactive mode", "npx @alan-jowett/promptkit", - "Detects your LLM CLI (Copilot / Claude) and\nlaunches an interactive prompt-building session", - ACCENT), - ("Browse templates", "npx @alan-jowett/promptkit list", - "Lists all available templates with descriptions\nAdd --json for machine-readable output", - ACCENT2), - ("Assemble a prompt", 'npx @alan-jowett/promptkit assemble investigate-bug \\\n' - ' -p problem_description="Segfault on startup" \\\n -o investigation.md', - "Composes persona + protocols + format + template\ninto a single ready-to-use prompt file", - ACCENT3), -] - -for i, (label, cmd, desc, color) in enumerate(commands): - y = Inches(1.6 + i * 1.8) - # label - add_text(s, Inches(0.9), y, Inches(3), Inches(0.35), - label, font_size=18, color=color, bold=True) - # code block - code_rect = add_rounded_rect(s, Inches(0.9), y + Inches(0.4), - Inches(7.5), Inches(0.9), CODE_BG) - add_text(s, Inches(1.1), y + Inches(0.45), Inches(7.1), Inches(0.8), - cmd, font_size=14, color=ACCENT2, font_name="Cascadia Code", - line_spacing=1.4) - # description - add_text(s, Inches(8.8), y + Inches(0.35), Inches(4), Inches(1.0), - desc, font_size=13, color=DIM) - -add_text(s, Inches(0.9), Inches(7.0), Inches(11), Inches(0.3), - "Prerequisites: Node.js 18+ · Optional: GitHub Copilot CLI or Claude Code for interactive mode", - font_size=12, color=DIM) - -speaker_notes(s, - "Live demo opportunity. Show each command in sequence. Interactive mode is the " - "flagship UX — it walks the user through component selection and parameter gathering. " - "The assemble command is for automation/scripting. List is for discovery.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 7 — Assembly Flow (visual) -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "How Assembly Works") - -steps = [ - ("Persona", "# Identity\nYou are a senior\nsystems engineer …", ACCENT), - ("Protocols", "# Reasoning\n## Anti-Hallucination\n## Root-Cause …", ACCENT2), - ("Format", "# Output Format\nInvestigation Report\nwith sections …", ACCENT3), - ("Template", "# Task\nInvestigate the bug:\n{{problem_description}}", ORANGE), -] - -box_w = Inches(2.5) -box_h = Inches(3.2) -arrow_w = Inches(0.6) -total_w = len(steps) * box_w.inches + (len(steps) - 1) * arrow_w.inches -sx = (13.333 - total_w) / 2 -y = Inches(1.8) - -for i, (label, content, color) in enumerate(steps): - x = Inches(sx + i * (box_w.inches + arrow_w.inches)) - add_rounded_rect(s, x, y, box_w, box_h, SURFACE) - # color top bar - s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, box_w, Inches(0.06) - ).fill.solid() - s.shapes[-1].fill.fore_color.rgb = color - s.shapes[-1].line.fill.background() - # label - add_text(s, x + Inches(0.15), y + Inches(0.2), box_w - Inches(0.3), Inches(0.35), - label, font_size=18, color=color, bold=True, alignment=PP_ALIGN.CENTER) - # content - add_text(s, x + Inches(0.15), y + Inches(0.7), box_w - Inches(0.3), Inches(2.2), - content, font_size=12, color=DIM, font_name="Cascadia Code", - alignment=PP_ALIGN.LEFT, line_spacing=1.5) - # arrow - if i < len(steps) - 1: - ax = x + box_w + Inches(0.1) - add_text(s, ax, y + Inches(1.2), arrow_w, Inches(0.5), - "→", font_size=28, color=DIM, alignment=PP_ALIGN.CENTER) - -# result box -result_y = Inches(5.4) -add_rounded_rect(s, Inches(2), result_y, Inches(9.3), Inches(1.2), CODE_BG) -add_text(s, Inches(2.3), result_y + Inches(0.1), Inches(8.7), Inches(1.0), - "Output: Single composed prompt file ─ ready to paste into any LLM\n" - "or use as agent instructions (.github/instructions/*.md, CLAUDE.md, .cursorrules)", - font_size=14, color=ACCENT, alignment=PP_ALIGN.CENTER, line_spacing=1.5) - -speaker_notes(s, - "Visual walkthrough of assembly. The engine reads the template's YAML frontmatter, " - "resolves each referenced component, and concatenates them in order. Parameters like " - "{{problem_description}} are substituted with user-provided values. The output is a " - "single markdown file that can be pasted into any LLM or saved as persistent agent instructions.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 8 — Pipeline Chaining -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Pipeline Chaining: Multi-Stage Workflows") - -pipeline_steps = [ - ("author-\nrequirements-doc", "requirements-\ndocument", ACCENT), - ("author-\ndesign-doc", "design-\ndocument", ACCENT2), - ("author-\nvalidation-plan", "validation-\nplan", ACCENT3), -] - -box_w = Inches(2.8) -box_h = Inches(2.5) -arrow_w = Inches(0.8) -total_w = len(pipeline_steps) * box_w.inches + (len(pipeline_steps) - 1) * arrow_w.inches -sx = (13.333 - total_w) / 2 -y = Inches(2.0) - -for i, (template, artifact, color) in enumerate(pipeline_steps): - x = Inches(sx + i * (box_w.inches + arrow_w.inches)) - add_rounded_rect(s, x, y, box_w, box_h, SURFACE) - s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, box_w, Inches(0.06) - ).fill.solid() - s.shapes[-1].fill.fore_color.rgb = color - s.shapes[-1].line.fill.background() - add_text(s, x + Inches(0.1), y + Inches(0.25), box_w - Inches(0.2), Inches(0.9), - template, font_size=16, color=WHITE, bold=True, - alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") - # produces label - add_text(s, x + Inches(0.1), y + Inches(1.35), box_w - Inches(0.2), Inches(0.3), - "produces ↓", font_size=12, color=DIM, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.1), y + Inches(1.7), box_w - Inches(0.2), Inches(0.7), - artifact, font_size=14, color=color, alignment=PP_ALIGN.CENTER, - font_name="Cascadia Code") - # arrow between boxes - if i < len(pipeline_steps) - 1: - ax = x + box_w + Inches(0.05) - add_text(s, ax, y + Inches(0.8), arrow_w, Inches(0.5), - "→", font_size=36, color=DIM, alignment=PP_ALIGN.CENTER) - -# explanation -add_text(s, Inches(1.5), Inches(5.0), Inches(10), Inches(1.5), - "Each template declares input/output contracts.\n" - "One template's artifact becomes the next template's input.\n" - "Build complete document lifecycles without copy-paste.", - font_size=16, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.6) - -speaker_notes(s, - "Pipeline chaining is the power feature. Templates declare input_contract and " - "output_contract with artifact types. The requirements doc feeds into design, " - "design feeds into validation planning. The bootstrap engine can suggest the " - "next stage automatically. This replaces ad-hoc copy-paste between tools.") - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 9 — Get Involved -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Get Started Today") - -actions = [ - ("Try it now", - "npx @alan-jowett/promptkit", - "Zero install — just run it. Walks you through\ntemplate selection and prompt assembly.", ACCENT), - ("Browse the repo", - "github.com/microsoft/promptkit", - "Read the templates, protocols, personas.\nUnderstand the composition model.", ACCENT2), - ("Contribute", - "Use the extend-library template", - "Add your own personas, protocols, or templates.\nPromptKit eats its own dog food — the contribution\nworkflow is itself a PromptKit template.", ACCENT3), - ("Share feedback", - "File issues or start discussions", - "What templates are missing? What workflows\ndo you wish PromptKit supported?", ORANGE), -] - -for i, (title, cmd, desc, color) in enumerate(actions): - y = Inches(1.55 + i * 1.35) - add_accent_bar(s, Inches(0.9), y, height=Inches(0.9), color=color) - add_text(s, Inches(1.2), y - Inches(0.02), Inches(4), Inches(0.35), - title, font_size=20, color=color, bold=True) - add_text(s, Inches(1.2), y + Inches(0.35), Inches(5), Inches(0.35), - cmd, font_size=14, color=WHITE, font_name="Cascadia Code") - add_text(s, Inches(7), y + Inches(0.05), Inches(5.5), Inches(0.8), - desc, font_size=13, color=DIM) - -speaker_notes(s, - "Call to action. The barrier to entry is one npx command. Encourage the team to " - "try it on a real task — bug investigation or code review works great as a first use. " - "The extend-library template is meta: you use PromptKit to contribute to PromptKit.") - - -# ════════════════════════════════════════════════════════════════ -# Save -# ════════════════════════════════════════════════════════════════ -out = "PromptKit-Intro-v2.pptx" -prs.save(out) -print(f"✅ Created {out}") diff --git a/create_pptx_deepdive.py b/create_pptx_deepdive.py deleted file mode 100644 index 6c6b92c..0000000 --- a/create_pptx_deepdive.py +++ /dev/null @@ -1,980 +0,0 @@ -"""Generate a PromptKit deep-dive presentation (15-18 slides, engineering audience).""" - -from pptx import Presentation -from pptx.util import Inches, Pt, Emu -from pptx.dml.color import RGBColor -from pptx.enum.text import PP_ALIGN, MSO_ANCHOR -from pptx.enum.shapes import MSO_SHAPE - -# ── Theme colours ────────────────────────────────────────────── -BG = RGBColor(0x1E, 0x1E, 0x2E) -ACCENT = RGBColor(0x89, 0xB4, 0xFA) # blue -ACCENT2 = RGBColor(0xA6, 0xE3, 0xA1) # green -ACCENT3 = RGBColor(0xF9, 0xE2, 0xAF) # yellow -ORANGE = RGBColor(0xFA, 0xB3, 0x87) -PINK = RGBColor(0xF3, 0x8B, 0xA8) -MAUVE = RGBColor(0xCB, 0xA6, 0xF7) -WHITE = RGBColor(0xCD, 0xD6, 0xF4) -DIM = RGBColor(0x6C, 0x70, 0x86) -SURFACE = RGBColor(0x31, 0x32, 0x44) -CODE_BG = RGBColor(0x18, 0x18, 0x25) - -W = Inches(13.333) -H = Inches(7.5) - -prs = Presentation() -prs.slide_width = W -prs.slide_height = H - -# ── helpers ──────────────────────────────────────────────────── -def dark_bg(slide): - fill = slide.background.fill - fill.solid() - fill.fore_color.rgb = BG - -def add_text(slide, left, top, width, height, text, *, - font_size=18, color=WHITE, bold=False, alignment=PP_ALIGN.LEFT, - font_name="Segoe UI", line_spacing=1.2): - txBox = slide.shapes.add_textbox(left, top, width, height) - tf = txBox.text_frame - tf.word_wrap = True - p = tf.paragraphs[0] - p.text = text - p.font.size = Pt(font_size) - p.font.color.rgb = color - p.font.bold = bold - p.font.name = font_name - p.alignment = alignment - p.space_after = Pt(font_size * 0.3) - if line_spacing != 1.0: - p.line_spacing = Pt(font_size * line_spacing) - return tf - -def add_para(tf, text, *, font_size=18, color=WHITE, bold=False, - font_name="Segoe UI", alignment=PP_ALIGN.LEFT, space_after=None, - line_spacing=None): - p = tf.add_paragraph() - p.text = text - p.font.size = Pt(font_size) - p.font.color.rgb = color - p.font.bold = bold - p.font.name = font_name - p.alignment = alignment - if space_after is not None: - p.space_after = Pt(space_after) - if line_spacing is not None: - p.line_spacing = Pt(line_spacing) - return p - -def add_rounded_rect(slide, left, top, width, height, fill_color=SURFACE): - shape = slide.shapes.add_shape( - MSO_SHAPE.ROUNDED_RECTANGLE, left, top, width, height) - shape.fill.solid() - shape.fill.fore_color.rgb = fill_color - shape.line.fill.background() - shape.shadow.inherit = False - return shape - -def add_rect(slide, left, top, width, height, fill_color): - shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, width, height) - shape.fill.solid() - shape.fill.fore_color.rgb = fill_color - shape.line.fill.background() - return shape - -def title_strip(slide, title, subtitle=None): - add_rect(slide, Inches(0), Inches(0), W, Inches(0.06), ACCENT) - add_text(slide, Inches(0.8), Inches(0.35), Inches(11), Inches(0.65), - title, font_size=32, color=WHITE, bold=True) - if subtitle: - add_text(slide, Inches(0.8), Inches(0.95), Inches(11), Inches(0.45), - subtitle, font_size=16, color=DIM) - -def speaker_notes(slide, text): - slide.notes_slide.notes_text_frame.text = text - -def code_block(slide, left, top, width, height, text, *, font_size=12): - add_rounded_rect(slide, left, top, width, height, CODE_BG) - add_text(slide, left + Inches(0.2), top + Inches(0.1), - width - Inches(0.4), height - Inches(0.2), - text, font_size=font_size, color=ACCENT2, - font_name="Cascadia Code", line_spacing=1.5) - -def slide_number(slide, num, total): - add_text(slide, Inches(12.2), Inches(7.1), Inches(1), Inches(0.3), - f"{num} / {total}", font_size=10, color=DIM, - alignment=PP_ALIGN.RIGHT) - -TOTAL_SLIDES = 16 - -# ════════════════════════════════════════════════════════════════ -# SLIDE 1 — Title -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -add_rect(s, Inches(0), Inches(0), W, Inches(0.08), ACCENT) - -logo_size = Inches(2.5) -s.shapes.add_picture("PromptKit-logo.png", Inches(0.9), Inches(1.2), - logo_size, logo_size) - -add_text(s, Inches(3.7), Inches(1.6), Inches(9), Inches(1.2), - "PromptKit", font_size=64, color=WHITE, bold=True) -add_text(s, Inches(3.7), Inches(2.8), Inches(9), Inches(0.8), - "Composable, version-controlled prompts\nfor AI-assisted software engineering", - font_size=24, color=ACCENT) -add_text(s, Inches(3.7), Inches(4.1), Inches(9), Inches(0.5), - "github.com/microsoft/promptkit · MIT License · v0.1.0", - font_size=14, color=DIM) -add_text(s, Inches(0.9), Inches(6.2), Inches(11), Inches(0.4), - "Deep Dive · Architecture & Internals", - font_size=14, color=DIM) -speaker_notes(s, "Title slide. This is the deep-dive version covering architecture, " - "component internals, assembly engine, testing methodology, and pipeline chaining.") -slide_number(s, 1, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 2 — The Problem -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Problem with Ad-Hoc Prompts") - -problems = [ - ("Written once, pasted everywhere", "No iteration, no improvement loop, no review process", ORANGE), - ("No version control", "Can't diff, blame, or revert prompt changes", ACCENT3), - ("No reuse", "Every engineer reinvents persona, guardrails, output format", ACCENT), - ("No testing", "No way to verify quality or catch regressions", ACCENT2), - ("Inconsistent outputs", "Same task → wildly different results across the team", PINK), -] -for i, (title, desc, color) in enumerate(problems): - y = Inches(1.65 + i * 1.0) - add_rect(s, Inches(0.9), y, Inches(0.06), Inches(0.6), color) - add_text(s, Inches(1.15), y - Inches(0.03), Inches(4), Inches(0.35), - title, font_size=20, color=WHITE, bold=True) - add_text(s, Inches(1.15), y + Inches(0.32), Inches(10), Inches(0.35), - desc, font_size=15, color=DIM) -speaker_notes(s, "Walk through each pain point. The core insight: prompts are the " - "primary interface to AI tools, but we treat them as throwaway text.") -slide_number(s, 2, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 3 — The Fix -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Fix: Treat Prompts as Code") - -pillars = [ - ("Modular", "Compose from reusable\nbuilding blocks", ACCENT), - ("Version-\nControlled", "Track changes in Git\nlike any code", ACCENT2), - ("Testable", "Reference-compare\nagainst known-good", ACCENT3), - ("Extensible", "Add your own\ncomponents via PR", ORANGE), -] -card_w = Inches(2.6) -gap = Inches(0.35) -total = len(pillars) * card_w.inches + (len(pillars) - 1) * gap.inches -sx = (13.333 - total) / 2 -for i, (title, desc, color) in enumerate(pillars): - x = Inches(sx + i * (card_w.inches + gap.inches)) - y = Inches(2.0) - add_rounded_rect(s, x, y, card_w, Inches(2.5), SURFACE) - add_rect(s, x, y, card_w, Inches(0.06), color) - add_text(s, x + Inches(0.2), y + Inches(0.3), card_w - Inches(0.4), Inches(0.5), - title, font_size=20, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.2), y + Inches(1.0), card_w - Inches(0.4), Inches(1.2), - desc, font_size=15, color=WHITE, alignment=PP_ALIGN.CENTER) - -add_text(s, Inches(1.5), Inches(5.2), Inches(10), Inches(0.8), - "PromptKit applies the same engineering discipline you use for software\n" - "to the prompts that build it.", - font_size=16, color=DIM, alignment=PP_ALIGN.CENTER) -speaker_notes(s, "Four engineering principles. Modularity = compose layers. " - "Version control = full Git history. Testable = reference comparison methodology. " - "Extensible = anyone can contribute new components.") -slide_number(s, 3, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 4 — Architecture: 5-Layer Stack -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Architecture: The 5-Layer Composition Stack") - -layers = [ - ("① Persona", "Who the LLM becomes", "systems-engineer, security-auditor …", ACCENT), - ("② Protocols", "How it reasons + guardrails", "anti-hallucination, root-cause-analysis …", ACCENT2), - ("③ Format", "Output structure & rules", "investigation-report, design-doc …", ACCENT3), - ("④ Taxonomy", "Domain classification (opt.)", "severity tiers, risk categories", ORANGE), - ("⑤ Template", "The task with {{params}}", "investigate-bug, review-code …", PINK), -] -for i, (name, role, examples, color) in enumerate(layers): - y = Inches(1.55 + i * 1.05) - bar_w = Inches(11.5 - i * 0.6) - x = Inches((13.333 - bar_w.inches) / 2) - add_rounded_rect(s, x, y, bar_w, Inches(0.85), SURFACE) - add_rect(s, x, y, Inches(0.07), Inches(0.85), color) - add_text(s, x + Inches(0.25), y + Inches(0.05), Inches(2.2), Inches(0.4), - name, font_size=18, color=color, bold=True) - add_text(s, x + Inches(2.5), y + Inches(0.05), Inches(3), Inches(0.4), - role, font_size=15, color=WHITE) - add_text(s, x + Inches(2.5), y + Inches(0.42), bar_w - Inches(2.7), Inches(0.4), - examples, font_size=12, color=DIM) - -add_text(s, Inches(1), Inches(6.9), Inches(11), Inches(0.4), - "Templates declare which components to compose via YAML frontmatter → " - "the bootstrap engine snaps them together", - font_size=13, color=DIM, alignment=PP_ALIGN.CENTER) -speaker_notes(s, "The composition stack. Each layer constrains the next. Templates " - "declare their dependencies in YAML frontmatter — persona, protocols, format. " - "The narrowing visual shows how the stack funnels into a specific task.") -slide_number(s, 4, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 5 — Deep Dive: Personas -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Deep Dive: Personas", "Layer ① — Who the LLM becomes") - -# Left: YAML frontmatter example -code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(3.0), - "---\n" - "name: systems-engineer\n" - "description: >\n" - " Senior systems engineer with deep\n" - " expertise in memory management,\n" - " concurrency, and performance.\n" - "domain:\n" - " - systems programming\n" - " - debugging\n" - " - performance analysis\n" - "tone: precise, technical, methodical\n" - "---", font_size=13) - -# Right: behavioral constraints -add_text(s, Inches(6.8), Inches(1.5), Inches(5.5), Inches(0.35), - "Behavioral Constraints", font_size=20, color=ACCENT, bold=True) -constraints = [ - "Reason from first principles — trace causality, never guess", - "Distinguish epistemic states — label KNOWN / INFERRED / ASSUMED", - "Prefer correctness over cleverness", - "Explicit uncertainty — say what's missing", - "No hallucination — refuse to fabricate", -] -for i, c in enumerate(constraints): - add_text(s, Inches(6.8), Inches(2.1 + i * 0.55), Inches(5.8), Inches(0.5), - f" • {c}", font_size=13, color=WHITE) - -# Bottom: all personas -add_rounded_rect(s, Inches(0.8), Inches(5.2), Inches(11.7), Inches(1.6), SURFACE) -add_text(s, Inches(1.1), Inches(5.3), Inches(11), Inches(0.35), - "Available Personas", font_size=16, color=ACCENT3, bold=True) -personas = [ - ("systems-engineer", "Memory, concurrency, debugging"), - ("security-auditor", "Vulnerability discovery, threat modeling"), - ("software-architect", "System design, API contracts, tradeoffs"), - ("devops-engineer", "CI/CD, release engineering, IaC"), - ("reverse-engineer", "Spec extraction from existing code"), - ("spl-contributor", "Library architecture, conventions"), -] -for i, (name, desc) in enumerate(personas): - col = i % 3 - row = i // 3 - x = Inches(1.1 + col * 3.9) - y = Inches(5.75 + row * 0.5) - add_text(s, x, y, Inches(1.8), Inches(0.35), - name, font_size=11, color=ACCENT, bold=True, font_name="Cascadia Code") - add_text(s, x + Inches(1.85), y, Inches(2), Inches(0.35), - desc, font_size=11, color=DIM) - -speaker_notes(s, "Personas define identity, domain expertise, tone, and behavioral " - "constraints. The YAML frontmatter is machine-readable; the markdown body contains " - "the actual prompt content. Key: behavioral constraints reinforce the protocols.") -slide_number(s, 5, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 6 — Deep Dive: Protocols (3 categories) -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Deep Dive: Protocols", "Layer ② — How the LLM reasons") - -cats = [ - ("Guardrails", "Cross-cutting, apply to all tasks", [ - ("anti-hallucination", "Epistemic labeling, refusal\nto fabricate, source attribution"), - ("self-verification", "LLM verifies its own output\nbefore finalizing"), - ("operational-constraints", "Scoping, tool usage,\nreproducibility"), - ], ACCENT), - ("Analysis", "Domain/language-specific checks", [ - ("memory-safety-c", "Allocation, pointers, buffers"), - ("memory-safety-rust", "unsafe blocks, FFI, interior mut"), - ("thread-safety", "Races, deadlocks, atomics"), - ("security-vulnerability", "Trust boundaries, auth, crypto"), - ], ACCENT2), - ("Reasoning", "Systematic approaches", [ - ("root-cause-analysis", "Hypothesis → evidence →\nelimination → root cause"), - ("requirements-elicitation", "Atomic, testable REQ-IDs\nwith RFC 2119 keywords"), - ("iterative-refinement", "Structure-preserving\nfeedback cycles"), - ], ACCENT3), -] - -col_w = Inches(3.7) -gap_x = Inches(0.35) -total_w = len(cats) * col_w.inches + (len(cats) - 1) * gap_x.inches -sx = (13.333 - total_w) / 2 - -for ci, (cat_name, cat_desc, protocols, color) in enumerate(cats): - x = Inches(sx + ci * (col_w.inches + gap_x.inches)) - y = Inches(1.5) - card_h = Inches(5.5) - add_rounded_rect(s, x, y, col_w, card_h, SURFACE) - add_rect(s, x, y, col_w, Inches(0.06), color) - add_text(s, x + Inches(0.15), y + Inches(0.15), col_w - Inches(0.3), Inches(0.35), - cat_name, font_size=22, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.15), y + Inches(0.55), col_w - Inches(0.3), Inches(0.3), - cat_desc, font_size=11, color=DIM, alignment=PP_ALIGN.CENTER) - - for pi, (pname, pdesc) in enumerate(protocols): - py = y + Inches(1.05 + pi * 1.2) - add_rounded_rect(s, x + Inches(0.12), py, col_w - Inches(0.24), Inches(1.0), CODE_BG) - add_text(s, x + Inches(0.25), py + Inches(0.05), col_w - Inches(0.5), Inches(0.3), - pname, font_size=11, color=color, bold=True, font_name="Cascadia Code") - add_text(s, x + Inches(0.25), py + Inches(0.38), col_w - Inches(0.5), Inches(0.55), - pdesc, font_size=10, color=WHITE) - -speaker_notes(s, "Three protocol categories with different scoping rules. Guardrails are " - "cross-cutting (apply to every task). Analysis protocols are language/domain-specific. " - "Reasoning protocols define systematic methodologies. Separate files, not conditional blocks.") -slide_number(s, 6, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 7 — Anti-Hallucination Protocol (deep dive) -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Spotlight: Anti-Hallucination Protocol", - "The most important guardrail — prevents fabrication") - -rules = [ - ("Epistemic Labeling", - "Every claim tagged: KNOWN (directly stated), INFERRED (reasoned with " - "explicit chain), or ASSUMED (flagged with justification).\n" - "If ASSUMED > ~30% → stop and request more context.", - ACCENT), - ("Refusal to Fabricate", - "Do NOT invent function names, API signatures, config values, " - "file paths, or version numbers.\n" - 'Use [UNKNOWN: ] as placeholder.', - ORANGE), - ("Uncertainty Disclosure", - "Enumerate multiple interpretations rather than choosing silently. " - 'State: "Low confidence — depends on [assumption]. Verify by [action]."', - ACCENT3), - ("Source Attribution", - 'Indicate provenance: "per requirements doc §3.2" or "line 42 of auth.c".\n' - "Do NOT cite sources not provided.", - ACCENT2), - ("Scope Boundaries", - "If question falls outside provided context, say so explicitly.\n" - "List what additional information is needed.", - PINK), -] - -for i, (title, desc, color) in enumerate(rules): - y = Inches(1.5 + i * 1.12) - add_rect(s, Inches(0.8), y, Inches(0.06), Inches(0.85), color) - add_text(s, Inches(1.1), y - Inches(0.02), Inches(3), Inches(0.3), - title, font_size=18, color=color, bold=True) - add_text(s, Inches(4.0), y + Inches(0.02), Inches(8.5), Inches(0.85), - desc, font_size=12, color=WHITE, line_spacing=1.4) - -speaker_notes(s, "Deep dive into the anti-hallucination protocol. This is the single " - "most impactful guardrail. Epistemic labeling forces the LLM to be honest about " - "what it knows vs infers vs assumes. The 30% threshold prevents assumption-heavy outputs.") -slide_number(s, 7, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 8 — Root Cause Analysis Protocol -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Spotlight: Root Cause Analysis Protocol", - "5-phase structured reasoning methodology") - -phases = [ - ("Phase 1", "Symptom\nCharacterization", - "Observed vs expected, timeline,\nblast radius, deterministic?", ACCENT), - ("Phase 2", "Hypothesis\nGeneration", - "≥3 ranked hypotheses before\ninvestigating any. Include 1 non-obvious.", ACCENT2), - ("Phase 3", "Evidence &\nElimination", - "Minimal investigation per hypothesis.\nCONFIRMED / ELIMINATED / INCONCLUSIVE", ACCENT3), - ("Phase 4", "Root Cause\nIdentification", - "Distinguish root from proximate.\nTrace full causal chain.", ORANGE), - ("Phase 5", "Remediation", - "Fix root, not symptom.\nSecondary fixes + risk assessment.", PINK), -] - -box_w = Inches(2.1) -gap = Inches(0.3) -total_w = len(phases) * box_w.inches + (len(phases) - 1) * gap.inches -sx = (13.333 - total_w) / 2 -y = Inches(1.7) - -for i, (label, title, desc, color) in enumerate(phases): - x = Inches(sx + i * (box_w.inches + gap.inches)) - add_rounded_rect(s, x, y, box_w, Inches(3.5), SURFACE) - add_rect(s, x, y, box_w, Inches(0.06), color) - add_text(s, x + Inches(0.1), y + Inches(0.2), box_w - Inches(0.2), Inches(0.25), - label, font_size=11, color=DIM, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.1), y + Inches(0.5), box_w - Inches(0.2), Inches(0.7), - title, font_size=16, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.1), y + Inches(1.5), box_w - Inches(0.2), Inches(1.6), - desc, font_size=11, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.4) - if i < len(phases) - 1: - add_text(s, x + box_w + Inches(0.02), y + Inches(1.4), Inches(0.3), Inches(0.4), - "→", font_size=24, color=DIM, alignment=PP_ALIGN.CENTER) - -# Key insight callout -add_rounded_rect(s, Inches(1.5), Inches(5.6), Inches(10.3), Inches(1.2), CODE_BG) -add_text(s, Inches(1.8), Inches(5.7), Inches(9.7), Inches(1.0), - 'Key rule: "If we fix only the proximate cause, will the root cause\n' - 'produce other failures?" → If yes, the fix is incomplete.\n\n' - 'Example: Proximate = "null deref at line 42" · Root = "init silently fails when config missing"', - font_size=13, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.4) - -speaker_notes(s, "The RCA protocol enforces systematic debugging. The ≥3 hypothesis rule " - "prevents anchoring bias. The root vs proximate distinction is critical — most quick fixes " - "only address the proximate cause and leave the root cause to produce more bugs.") -slide_number(s, 8, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 9 — Deep Dive: Formats -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Deep Dive: Output Formats", "Layer ③ — Structured deliverables") - -# Left: format frontmatter -code_block(s, Inches(0.8), Inches(1.5), Inches(4.2), Inches(1.5), - "---\n" - "name: investigation-report\n" - "type: format\n" - "produces: investigation-report\n" - "---", font_size=13) - -# Left: section list -add_text(s, Inches(0.8), Inches(3.3), Inches(4.2), Inches(0.35), - "Investigation Report Structure", font_size=16, color=ACCENT, bold=True) -sections = [ - "1. Executive Summary (2-4 sentences)", - "2. Problem Statement", - "3. Investigation Scope + limitations", - "4. Findings (F-NNN, severity-ordered)", - "5. Root Cause Analysis (causal chain)", - "6. Remediation Plan (priority table)", - "7. Prevention (code + process + tooling)", - "8. Open Questions", - "9. Revision History", -] -for i, sec in enumerate(sections): - add_text(s, Inches(0.8), Inches(3.8 + i * 0.36), Inches(4.2), Inches(0.35), - sec, font_size=12, color=WHITE if i < 7 else DIM) - -# Right: all formats table -add_text(s, Inches(5.5), Inches(1.5), Inches(7), Inches(0.35), - "All Available Formats", font_size=18, color=ACCENT3, bold=True) -formats = [ - ("requirements-doc", "Numbered REQ-IDs + acceptance criteria", "requirements-document"), - ("design-doc", "Architecture, APIs, tradeoff analysis", "design-document"), - ("validation-plan", "Test cases + traceability matrix", "validation-plan"), - ("investigation-report", "Findings, RCA, remediation", "investigation-report"), - ("implementation-plan", "Task breakdown + dependencies", "implementation-plan"), - ("agent-instructions", ".github/instructions/, CLAUDE.md, .cursorrules", "agent-instructions"), - ("pipeline-spec", "YAML pipelines + design rationale", "pipeline-spec"), - ("release-notes", "Changelog, breaking changes, upgrade path", "release-notes"), - ("multi-artifact", "Multiple structured files", "multi-artifact"), -] - -# header -add_rounded_rect(s, Inches(5.5), Inches(2.0), Inches(7.3), Inches(0.4), ACCENT) -add_text(s, Inches(5.7), Inches(2.05), Inches(2.2), Inches(0.3), - "Format", font_size=12, color=BG, bold=True) -add_text(s, Inches(7.9), Inches(2.05), Inches(2.8), Inches(0.3), - "Produces", font_size=12, color=BG, bold=True) -add_text(s, Inches(10.7), Inches(2.05), Inches(2), Inches(0.3), - "Artifact Type", font_size=12, color=BG, bold=True) - -for i, (name, desc, artifact) in enumerate(formats): - y = Inches(2.5 + i * 0.48) - bg = SURFACE if i % 2 == 0 else CODE_BG - add_rounded_rect(s, Inches(5.5), y, Inches(7.3), Inches(0.42), bg) - add_text(s, Inches(5.7), y + Inches(0.05), Inches(2.1), Inches(0.3), - name, font_size=10, color=ACCENT, font_name="Cascadia Code") - add_text(s, Inches(7.9), y + Inches(0.05), Inches(2.7), Inches(0.3), - desc, font_size=10, color=WHITE) - add_text(s, Inches(10.7), y + Inches(0.05), Inches(2), Inches(0.3), - artifact, font_size=9, color=DIM, font_name="Cascadia Code") - -speaker_notes(s, "Formats define the output structure. The investigation-report format " - "has 9 sections with strict ordering rules. The 'produces' field enables pipeline " - "chaining — formats declare what artifact type they generate.") -slide_number(s, 9, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 10 — Deep Dive: Templates (frontmatter) -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Deep Dive: Template Anatomy", "Layer ⑤ — The task declaration") - -# Left: real frontmatter -code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(5.0), - "---\n" - "name: investigate-bug\n" - "description: >\n" - " Systematically investigate a bug.\n" - " Apply root cause analysis and produce\n" - " an investigation report.\n" - "\n" - "persona: systems-engineer\n" - "\n" - "protocols:\n" - " - guardrails/anti-hallucination\n" - " - guardrails/self-verification\n" - " - guardrails/operational-constraints\n" - " - reasoning/root-cause-analysis\n" - "\n" - "format: investigation-report\n" - "\n" - "params:\n" - " problem_description: \"Bug description\"\n" - " code_context: \"Relevant code/logs\"\n" - " environment: \"OS, runtime, build\"\n" - "\n" - "input_contract: null\n" - "output_contract:\n" - " type: investigation-report\n" - "---", font_size=12) - -# Right: field explanations -fields = [ - ("persona:", "References one persona file.\nBecomes the # Identity section.", ACCENT), - ("protocols:", "List of category/name paths.\nEach loaded as # Reasoning Protocol.", ACCENT2), - ("format:", "References one format file.\nBecomes the # Output Format section.", ACCENT3), - ("params:", "Key-value map → {{param}} placeholders\nin template body get substituted.", ORANGE), - ("input_contract:", "What artifact this template consumes.\nnull = no prerequisite.", PINK), - ("output_contract:", "What artifact this template produces.\nEnables pipeline chaining.", MAUVE), -] - -for i, (field, desc, color) in enumerate(fields): - y = Inches(1.5 + i * 0.9) - add_text(s, Inches(6.7), y, Inches(2.5), Inches(0.3), - field, font_size=15, color=color, bold=True, font_name="Cascadia Code") - add_text(s, Inches(6.7), y + Inches(0.32), Inches(6), Inches(0.55), - desc, font_size=12, color=WHITE, line_spacing=1.4) - -speaker_notes(s, "Template frontmatter is the composition declaration. The key insight: " - "protocols use category/name paths (guardrails/anti-hallucination) while the manifest " - "uses short names (anti-hallucination). CI validates they stay in sync.") -slide_number(s, 10, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 11 — The Manifest -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Manifest: Source of Truth", "manifest.yaml — the component registry") - -# Left: manifest structure -code_block(s, Inches(0.8), Inches(1.5), Inches(5.5), Inches(5.2), - "# manifest.yaml\n" - "version: \"0.1.0\"\n" - "\n" - "personas:\n" - " - name: systems-engineer\n" - " path: personas/systems-engineer.md\n" - "\n" - "protocols:\n" - " guardrails:\n" - " - name: anti-hallucination\n" - " path: protocols/guardrails/...\n" - " analysis:\n" - " - name: memory-safety-c\n" - " path: protocols/analysis/...\n" - " reasoning:\n" - " - name: root-cause-analysis\n" - " path: protocols/reasoning/...\n" - "\n" - "formats:\n" - " - name: investigation-report\n" - " path: formats/investigation-report.md\n" - " produces: investigation-report\n" - "\n" - "templates:\n" - " investigation:\n" - " - name: investigate-bug\n" - " protocols: [anti-hallucination, ...]\n" # short names! - " format: investigation-report\n" - "\n" - "pipelines:\n" - " document-lifecycle:\n" - " stages:\n" - " - template: author-requirements-doc\n" - " produces: requirements-document", font_size=11) - -# Right: key rules -add_text(s, Inches(6.8), Inches(1.5), Inches(5.5), Inches(0.35), - "Key Rules", font_size=20, color=ACCENT, bold=True) - -rules = [ - ("Protocol naming duality", - "Templates use category paths:\n guardrails/anti-hallucination\n" - "Manifest uses short names:\n anti-hallucination\n" - "CI enforces they stay in sync.", ACCENT), - ("Path resolution", - "Every component has a path field\npointing to its .md source file.\n" - "Assembly engine reads these paths.", ACCENT2), - ("Pipeline stages", - "produces/consumes fields enable\nthe bootstrap engine to validate\n" - "chaining and suggest next stages.", ACCENT3), - ("CI validation", - "tests/validate-manifest.py checks\nthat manifest protocols match\n" - "template frontmatter protocols.", ORANGE), -] -for i, (title, desc, color) in enumerate(rules): - y = Inches(2.1 + i * 1.25) - add_rect(s, Inches(6.8), y, Inches(0.06), Inches(1.0), color) - add_text(s, Inches(7.05), y, Inches(5.5), Inches(0.3), - title, font_size=14, color=color, bold=True) - add_text(s, Inches(7.05), y + Inches(0.3), Inches(5.5), Inches(0.7), - desc, font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) - -speaker_notes(s, "The manifest is the component registry. Critical detail: protocols have " - "a naming duality — templates use category/name paths, manifest uses short names. " - "CI (validate-manifest.py) enforces sync. This is the only automated check in the repo.") -slide_number(s, 11, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 12 — Bootstrap Flow -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "The Bootstrap Flow", "bootstrap.md — the meta-prompt that drives composition") - -steps = [ - ("1", "Understand\nthe task", "Ask user what they\nwant to accomplish", ACCENT), - ("2", "Read\nmanifest", "Discover all available\ncomponents", ACCENT2), - ("3", "Select\ntemplate", "Match task to\nbest template", ACCENT3), - ("4", "Check\nmode", "Interactive → execute\nSingle-shot → file", ORANGE), - ("5", "Collect\nparams", "Gather template-\nspecific inputs", PINK), - ("6", "Assemble", "Compose layers\nin order", MAUVE), - ("7", "Output", "Write prompt file\nor execute directly", ACCENT), -] - -box_w = Inches(1.55) -box_h = Inches(2.5) -gap = Inches(0.15) -total_w = len(steps) * box_w.inches + (len(steps) - 1) * gap.inches -sx = (13.333 - total_w) / 2 - -for i, (num, title, desc, color) in enumerate(steps): - x = Inches(sx + i * (box_w.inches + gap.inches)) - y = Inches(1.7) - add_rounded_rect(s, x, y, box_w, box_h, SURFACE) - add_rect(s, x, y, box_w, Inches(0.05), color) - # number circle - add_text(s, x + Inches(0.05), y + Inches(0.15), box_w - Inches(0.1), Inches(0.3), - num, font_size=24, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.05), y + Inches(0.55), box_w - Inches(0.1), Inches(0.7), - title, font_size=14, color=WHITE, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.05), y + Inches(1.4), box_w - Inches(0.1), Inches(1.0), - desc, font_size=10, color=DIM, alignment=PP_ALIGN.CENTER, line_spacing=1.4) - if i < len(steps) - 1: - add_text(s, x + box_w - Inches(0.05), y + Inches(1.0), Inches(0.35), Inches(0.3), - "›", font_size=20, color=DIM, alignment=PP_ALIGN.CENTER) - -# Two modes callout -add_rounded_rect(s, Inches(0.8), Inches(4.6), Inches(5.7), Inches(2.3), CODE_BG) -add_text(s, Inches(1.0), Inches(4.7), Inches(5.3), Inches(0.3), - "Single-Shot Mode (default)", font_size=15, color=ACCENT, bold=True) -add_text(s, Inches(1.0), Inches(5.1), Inches(5.3), Inches(1.0), - "Gather params → assemble prompt → write .md file\n" - "User pastes into any LLM session\n\n" - "Output options:\n" - " (a) Raw prompt file\n" - " (b) Agent instructions (.github/instructions/,\n" - " CLAUDE.md, .cursorrules)", - font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) - -add_rounded_rect(s, Inches(6.8), Inches(4.6), Inches(5.7), Inches(2.3), CODE_BG) -add_text(s, Inches(7.0), Inches(4.7), Inches(5.3), Inches(0.3), - "Interactive Mode", font_size=15, color=ACCENT2, bold=True) -add_text(s, Inches(7.0), Inches(5.1), Inches(5.3), Inches(1.0), - "Load components → execute directly in session\n" - "Reasoning-and-challenge phase before output\n\n" - "Template declares: mode: interactive\n" - "Used by: extend-library, interactive-design\n" - "No file written — LLM acts on the prompt live", - font_size=11, color=WHITE, font_name="Cascadia Code", line_spacing=1.3) - -speaker_notes(s, "The bootstrap flow is the core UX. bootstrap.md is itself a meta-prompt — " - "it instructs the LLM how to use PromptKit. Two modes: single-shot writes a file you " - "paste elsewhere; interactive executes the prompt live in the current session.") -slide_number(s, 12, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 13 — Assembly Engine Internals -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Assembly Engine Internals", "cli/lib/assemble.js — how the sausage is made") - -# Assembly order diagram -order_items = [ - ("# Identity", "Load persona .md, strip frontmatter", ACCENT), - ("# Reasoning Protocols", "Load each protocol .md, join with ---", ACCENT2), - ("# Output Format", "Load format .md, strip frontmatter", ACCENT3), - ("# Task", "Load template .md, substitute {{params}}", ORANGE), -] - -for i, (section, desc, color) in enumerate(order_items): - y = Inches(1.6 + i * 1.15) - add_rounded_rect(s, Inches(0.8), y, Inches(5.5), Inches(0.95), SURFACE) - add_rect(s, Inches(0.8), y, Inches(0.07), Inches(0.95), color) - add_text(s, Inches(1.1), y + Inches(0.08), Inches(2.5), Inches(0.35), - section, font_size=16, color=color, bold=True, font_name="Cascadia Code") - add_text(s, Inches(1.1), y + Inches(0.48), Inches(4.8), Inches(0.4), - desc, font_size=13, color=WHITE) - if i < len(order_items) - 1: - add_text(s, Inches(3.3), y + Inches(0.95), Inches(1), Inches(0.3), - "↓", font_size=18, color=DIM, alignment=PP_ALIGN.CENTER) - -# Right: key functions -add_text(s, Inches(6.8), Inches(1.6), Inches(5.5), Inches(0.3), - "Key Processing Steps", font_size=18, color=ACCENT, bold=True) - -funcs = [ - ("stripFrontmatter()", - "Removes YAML --- block from\neach component before assembly", ACCENT), - ("Strip HTML comments", - "Removes SPDX license headers\n( blocks)", ACCENT2), - ("loadComponent()", - "Reads file, strips frontmatter +\ncomments, returns clean body", ACCENT3), - ("Parameter substitution", - "Simple {{key}} → value replacement\nvia split/join (no recursion)", ORANGE), - ("Section joining", - "Sections separated by markdown\nhorizontal rule (---)", PINK), -] - -for i, (name, desc, color) in enumerate(funcs): - y = Inches(2.1 + i * 0.95) - add_text(s, Inches(6.8), y, Inches(3), Inches(0.25), - name, font_size=13, color=color, bold=True, font_name="Cascadia Code") - add_text(s, Inches(6.8), y + Inches(0.28), Inches(5.5), Inches(0.55), - desc, font_size=11, color=WHITE, line_spacing=1.3) - -# Bottom: output -add_rounded_rect(s, Inches(0.8), Inches(6.2), Inches(11.7), Inches(0.8), CODE_BG) -add_text(s, Inches(1.1), Inches(6.3), Inches(11.1), Inches(0.6), - "Output: Single markdown string → # Identity\\n---\\n# Reasoning Protocols\\n---\\n" - "# Output Format\\n---\\n# Task", - font_size=12, color=ACCENT, alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") - -speaker_notes(s, "The assembly engine is deliberately simple. It reads the manifest to " - "resolve component paths, loads each .md file, strips YAML frontmatter and SPDX headers, " - "wraps in section headers, joins with horizontal rules, and substitutes parameters. " - "No template language, no recursion, no magic — just concatenation in a specific order.") -slide_number(s, 13, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 14 — Pipeline Chaining -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Pipeline Chaining: Multi-Stage Workflows", - "Templates connected by input/output contracts") - -pipeline_steps = [ - ("author-\nrequirements-doc", "requirements-\ndocument", ACCENT), - ("author-\ndesign-doc", "design-\ndocument", ACCENT2), - ("author-\nvalidation-plan", "validation-\nplan", ACCENT3), -] - -box_w = Inches(2.8) -box_h = Inches(2.5) -arrow_w = Inches(0.8) -total_w = len(pipeline_steps) * box_w.inches + (len(pipeline_steps) - 1) * arrow_w.inches -sx = (13.333 - total_w) / 2 -y = Inches(1.7) - -for i, (template, artifact, color) in enumerate(pipeline_steps): - x = Inches(sx + i * (box_w.inches + arrow_w.inches)) - add_rounded_rect(s, x, y, box_w, box_h, SURFACE) - add_rect(s, x, y, box_w, Inches(0.06), color) - add_text(s, x + Inches(0.1), y + Inches(0.25), box_w - Inches(0.2), Inches(0.9), - template, font_size=16, color=WHITE, bold=True, - alignment=PP_ALIGN.CENTER, font_name="Cascadia Code") - add_text(s, x + Inches(0.1), y + Inches(1.35), box_w - Inches(0.2), Inches(0.3), - "produces ↓", font_size=12, color=DIM, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.1), y + Inches(1.7), box_w - Inches(0.2), Inches(0.7), - artifact, font_size=14, color=color, alignment=PP_ALIGN.CENTER, - font_name="Cascadia Code") - if i < len(pipeline_steps) - 1: - ax = x + box_w + Inches(0.05) - add_text(s, ax, y + Inches(0.8), arrow_w, Inches(0.5), - "→", font_size=36, color=DIM, alignment=PP_ALIGN.CENTER) - -# Contract mechanism -add_rounded_rect(s, Inches(0.8), Inches(4.6), Inches(11.7), Inches(2.4), CODE_BG) -add_text(s, Inches(1.1), Inches(4.7), Inches(5), Inches(0.3), - "How contracts work:", font_size=16, color=ACCENT, bold=True) - -contract_lines = [ - ("1.", "Template declares", "output_contract: { type: requirements-document }", ACCENT), - ("2.", "Next template declares", "input_contract: { type: requirements-document }", ACCENT2), - ("3.", "Manifest defines pipeline", "stages: [{produces: ...}, {consumes: ..., produces: ...}]", ACCENT3), - ("4.", "Bootstrap validates", "Previous output matches next input before offering template", ORANGE), - ("5.", "Artifacts flow forward", "Output of stage N becomes input parameter of stage N+1", PINK), -] - -for i, (num, label, detail, color) in enumerate(contract_lines): - y = Inches(5.15 + i * 0.35) - add_text(s, Inches(1.1), y, Inches(0.3), Inches(0.3), - num, font_size=12, color=color, bold=True) - add_text(s, Inches(1.4), y, Inches(2.3), Inches(0.3), - label, font_size=12, color=WHITE) - add_text(s, Inches(3.8), y, Inches(8.3), Inches(0.3), - detail, font_size=11, color=DIM, font_name="Cascadia Code") - -speaker_notes(s, "Pipeline chaining is the power feature. Templates declare input_contract " - "and output_contract with artifact types. The manifest defines pipeline stages. " - "The bootstrap engine validates contracts before offering the next template. " - "This replaces ad-hoc copy-paste between tools with a structured workflow.") -slide_number(s, 14, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 15 — Testing Methodology -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Testing: Reference Comparison Methodology", - "How do you test prompts? Compare against known-good references.") - -# Flow -flow_steps = [ - ("Hand-craft\nreference prompt", ACCENT), - ("Generate via\nPromptKit", ACCENT2), - ("Structured\ngap analysis", ACCENT3), - ("Feed gaps back\nas improvements", ORANGE), -] -box_w = Inches(2.5) -gap = Inches(0.5) -total_w = len(flow_steps) * box_w.inches + (len(flow_steps) - 1) * gap.inches -sx = (13.333 - total_w) / 2 - -for i, (label, color) in enumerate(flow_steps): - x = Inches(sx + i * (box_w.inches + gap.inches)) - add_rounded_rect(s, x, Inches(1.6), box_w, Inches(1.1), SURFACE) - add_rect(s, x, Inches(1.6), box_w, Inches(0.05), color) - add_text(s, x + Inches(0.1), Inches(1.75), box_w - Inches(0.2), Inches(0.8), - label, font_size=14, color=WHITE, bold=True, alignment=PP_ALIGN.CENTER) - if i < len(flow_steps) - 1: - add_text(s, x + box_w + Inches(0.08), Inches(1.9), Inches(0.4), Inches(0.4), - "→", font_size=24, color=DIM, alignment=PP_ALIGN.CENTER) - -# 5 dimensions -add_text(s, Inches(0.8), Inches(3.1), Inches(11), Inches(0.35), - "5 Gap Analysis Dimensions", font_size=20, color=ACCENT, bold=True) - -dimensions = [ - ("Task Framing", "Goal statement, success criteria,\nnon-goals, context definition", - "Is the objective clearly stated?\nIs scope explicitly bounded?", ACCENT), - ("Reasoning\nMethodology", "Systematic analysis, hypothesis\ngeneration, evidence requirements", - "Is anti-hallucination present?\nAre multiple hypotheses required?", ACCENT2), - ("Output\nSpecification", "Format structure, artifacts,\ntaxonomy, severity ranking", - "Is the deliverable structure defined?\nAre classification schemes provided?", ACCENT3), - ("Operational\nGuidance", "Scoping strategy, tool usage,\nstep-by-step plan", - "Does it guide how to scope work?\nIs a procedural plan provided?", ORANGE), - ("Quality\nAssurance", "Self-verification, sampling,\ncoverage, consistency", - "Must LLM verify its output?\nMust it document what it examined?", PINK), -] - -col_w = Inches(2.25) -gap_x = Inches(0.2) -total_w = len(dimensions) * col_w.inches + (len(dimensions) - 1) * gap_x.inches -sx = (13.333 - total_w) / 2 - -for i, (title, checks, questions, color) in enumerate(dimensions): - x = Inches(sx + i * (col_w.inches + gap_x.inches)) - add_rounded_rect(s, x, Inches(3.6), col_w, Inches(3.5), SURFACE) - add_rect(s, x, Inches(3.6), col_w, Inches(0.05), color) - add_text(s, x + Inches(0.1), Inches(3.75), col_w - Inches(0.2), Inches(0.55), - title, font_size=13, color=color, bold=True, alignment=PP_ALIGN.CENTER) - add_text(s, x + Inches(0.1), Inches(4.4), col_w - Inches(0.2), Inches(1.0), - checks, font_size=10, color=WHITE, alignment=PP_ALIGN.CENTER, line_spacing=1.3) - add_text(s, x + Inches(0.1), Inches(5.5), col_w - Inches(0.2), Inches(1.2), - questions, font_size=9, color=DIM, alignment=PP_ALIGN.CENTER, line_spacing=1.3) - -speaker_notes(s, "Testing prompts is hard because output is non-deterministic. The reference " - "comparison methodology sidesteps this: compare prompt structure, not LLM output. " - "Each dimension gets ✅ Covered / ⚠️ Partial / ❌ Missing classification. " - "Gaps feed back into the library as improvements.") -slide_number(s, 15, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -# SLIDE 16 — Get Involved -# ════════════════════════════════════════════════════════════════ -s = prs.slides.add_slide(prs.slide_layouts[6]) -dark_bg(s) -title_strip(s, "Get Started Today") - -actions = [ - ("Try it now", - "npx @alan-jowett/promptkit", - "Zero install — walks you through template\nselection and prompt assembly.", ACCENT), - ("Browse the repo", - "github.com/microsoft/promptkit", - "Read the templates, protocols, personas.\nUnderstand the composition model.", ACCENT2), - ("Contribute", - "Use the extend-library template", - "PromptKit eats its own dog food — the\ncontribution workflow is a PromptKit template.", ACCENT3), - ("Share feedback", - "File issues or start discussions", - "What templates are missing? What workflows\ndo you wish PromptKit supported?", ORANGE), -] - -for i, (title, cmd, desc, color) in enumerate(actions): - y = Inches(1.55 + i * 1.35) - add_rect(s, Inches(0.9), y, Inches(0.06), Inches(0.9), color) - add_text(s, Inches(1.2), y - Inches(0.02), Inches(4), Inches(0.35), - title, font_size=20, color=color, bold=True) - add_text(s, Inches(1.2), y + Inches(0.35), Inches(5), Inches(0.35), - cmd, font_size=14, color=WHITE, font_name="Cascadia Code") - add_text(s, Inches(7), y + Inches(0.05), Inches(5.5), Inches(0.8), - desc, font_size=13, color=DIM) - -speaker_notes(s, "Call to action. The barrier to entry is one npx command. " - "The extend-library template is meta: you use PromptKit to contribute to PromptKit.") -slide_number(s, 16, TOTAL_SLIDES) - - -# ════════════════════════════════════════════════════════════════ -out = "PromptKit-DeepDive.pptx" -prs.save(out) -print(f"✅ Created {out} ({TOTAL_SLIDES} slides)") diff --git a/docs/case-studies/audit-traceability.md b/docs/case-studies/audit-traceability.md index 55b4a41..c1c5da3 100644 --- a/docs/case-studies/audit-traceability.md +++ b/docs/case-studies/audit-traceability.md @@ -23,7 +23,7 @@ is directly contradicted by the design's synchronous API call chain. ### Assembling the Prompt ```bash -npx promptkit assemble audit-traceability \ +npx @alan-jowett/promptkit assemble audit-traceability \ -p project_name="Auth Service v2" \ -p requirements_doc="$(cat auth-requirements.md)" \ -p design_doc="$(cat auth-design.md)" \ diff --git a/docs/scenarios.md b/docs/scenarios.md index 9c4284c..3e8c54c 100644 --- a/docs/scenarios.md +++ b/docs/scenarios.md @@ -57,17 +57,19 @@ requirements document with stable identifiers. ### "The design doesn't match what we agreed on" You wrote a requirements document last month. Now the design document -is done, but you suspect it drifted — new features crept in, a -performance constraint might be violated, and some requirements seem -to have been quietly dropped. +and validation plan are done, but you suspect they drifted — new +features crept in, a performance constraint might be violated, and some +requirements seem to have been quietly dropped. -**Template:** `audit-traceability` (without the validation plan) · -**Taxonomy:** `specification-drift` - -**What you get:** A two-document audit identifying orphaned design -decisions (D3), untraced requirements (D1), assumption drift (D5), -and constraint violations (D6). Each finding has specific document -locations and a recommended resolution. +**Template:** `audit-traceability` · **Persona:** `specification-analyst` · +**Taxonomy:** `specification-drift` (D1–D7) + +**What you get:** A three-document audit identifying untraced +requirements (D1), untested requirements (D2), orphaned design +decisions (D3), orphaned test cases (D4), assumption drift (D5), +constraint violations (D6), and acceptance criteria mismatches (D7). +Each finding has specific document locations and a recommended +resolution. ### "Review this PR for memory safety"