feat(skills): executive technical explainer capability (3 skills + technical-explainer profile) - #329
Open
wz-gsa wants to merge 1 commit into
Open
feat(skills): executive technical explainer capability (3 skills + technical-explainer profile)#329wz-gsa wants to merge 1 commit into
wz-gsa wants to merge 1 commit into
Conversation
…chnical-explainer profile) Add an evidence-grounded capability for explaining software development, agentic coding, and security controls to executive / non-engineering audiences — accurately, without hype, and without overclaiming agent autonomy, sandbox security, or secret handling. Skills (communications collection): - technical-concept-translator: one concept -> accurate executive mental model (what it is / plain language / why it matters / what it is NOT / where it fits / controls), backed by an executive concept library. - software-delivery-explainer: the delivery pipeline + where agents act and where the human control points are; thesis "more work between the controls, not fewer controls." - agentic-value-analyst: capability -> value without hype; five evidence classes; defensible metrics over vanity metrics; honest handling of conflicting research. Reference material (not skills): executive concept library (24 concepts, each with a "what it is not" and ground-truth citations to the playbook/quickstart), six audience profiles, and evidence/measurement guidance. Workflow: implement the previously-reserved `technical-explainer` profile in the design-artifact workflow by composing the three skills (no new renderer); add `technical-explainer` to schemas/taxonomy.yaml. Honesty properties are pinned by deterministic test-cases: the sandbox is stated as isolation not a perfect guarantee (image-provenance/SI-7 caveat); the secrets caveat is precise (host store; msb swap-on-wire; on sbx the USAi key is a custom unproxied secret visible to the agent, protected by isolation not proxying — so "secrets never enter the sandbox" is not asserted); the agent cannot self-approve or self-merge; the "50% faster" question is answered qualified/ranged with an evidence class; vanity metrics are flagged. Anti-fabrication: an ungrounded concept is flagged, not invented. Architecture (extend design-artifact, don't build parallel) chosen via nexus 7/7 higher-order consensus; adversarial accuracy/security/over-triggering review 7/7. make validate, make generate-check, 73/73 test-cases, and markdownlint all pass. Refs #319 #320 #321 #322 #323 #324 #325 Co-authored-by: OpenCode Agent <william.zujkowski@gsa.gov>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the core of epic #319 — an evidence-grounded capability for explaining software development, agentic coding, and security controls to executive / non-engineering audiences.
Quality bar: hand an agent a concept, process, or value question and it produces an explanation an executive understands without making an engineer wince at the inaccuracies.
What's in this PR
Skills (
communicationscollection)technical-concept-translator(skill: technical-concept-translator — one concept → accurate executive mental model #320) — one concept → accurate executive mental model (what it is / plain language / why it matters / what it is NOT / where it fits / controls). Backed by the concept library.software-delivery-explainer(skill: software-delivery-explainer — where agents act and where humans keep control #321) — the delivery pipeline + where agents act and where the human control points are; thesis "more work between the controls, not fewer controls."agentic-value-analyst(skill: agentic-value-analyst — capability → organizational value without AI hype #322) — value without hype; five evidence classes; defensible metrics over vanity metrics; honest handling of conflicting research.Reference material (not skills) (#324, #325)
concept-library.md— 24 concepts, each with a "what it is not" and ground-truthsource:citations to the playbook/quickstart.audience-profiles.md— CIO/CTO, CISO, CAIO, program exec, COO, acquisition.measurement-guidance.md— evidence classes, good vs. misleading metrics, cost/value framing.Workflow / profile (#323)
technical-explainerprofile indesign-artifactby composing the three skills (no new renderer). Addedtechnical-explainertoschemas/taxonomy.yaml.Honesty properties (pinned by deterministic test-cases)
Process
design-artifact, don't build parallel) chosen via nexus 7/7 higher-order consensus.plain-language-review/narrative-architect/renderers) applied.Validation
make validate✓ ·make generate-check✓ (INDEX/CATALOG regenerated) ·run_test_cases.py73/73 ✓ · markdownlint ✓Follow-on
repo-evidence-extractor(the "executive demo" input that reads a real repo/issue/PR) is tracked as a separate epic Epic (follow-on): repo-evidence-extractor — turn a real repo/issue/PR into a factual walkthrough for the explainer #328 so it gets its own threat model.Refs #319 #320 #321 #322 #323 #324 #325
AI-assisted (OpenCode).