Skill: completetech/agentic-discovery-skill (version 1.0.3)

--- name: agentic-discovery-skill description: >- Create CompleteTech LLC discovery and scoping artifacts for agentic development opportunities, including intake questionnaires, workflow discovery scripts, stakeholder interview guides, current/future-state workflow maps, systems/data readiness checklists, approval gate reviews, risk/excluded-use checks, success criteria, evaluation examples, pilot readiness scorecards, and proposal/SOW handoff briefs. Use before proposal, contract, invoice, or delivery work when Codex needs to gather verified facts for bounded agentic workflow services. version: 1.0.3 metadata: openclaw: skillKey: agentic-discovery-skill homepage: https://github.com/CompleteTech-LLC/agentic-discovery-skill requires: bins: - python3 install: - kind: uv package: reportlab==4.5.1 - kind: uv package: pypdfium2==5.8.0 - kind: uv package: pillow==12.2.0 - kind: uv package: pyyaml==6.0.3 --- # Agentic Discovery Skill ## Purpose Create discovery and scoping artifacts that turn an agentic development opportunity into verified facts for proposal/SOW, contract, invoice, and delivery work. ## System Boundary This skill owns pre-sale fact-finding and scoping. Hand off to `agentic-proposal-skill` for buyer-facing scope and SOW documents, `agentic-security-review-skill` for formal security or launch risk review, `agentic-delivery-skill` after approval, and `agentic-customer-success-skill` for ongoing relationship management. Do not use discovery artifacts as final proposals, contracts, invoices, launch signoffs, or public proof. ## Core Workflow 1. Identify the discovery need: qualification, intake, stakeholder interview, workflow map, readiness check, risk review, success criteria, evaluation examples, prioritization, recap, or proposal handoff. 2. Gather verified facts only: repeated workflow, inputs, systems, tools, retrieval sources, decision points, approval gates, risks, exclusions, logging, monitoring, documentation, support, and handoff needs. 3. Use `references/use-case-decision-table.md` to choose the right artifact. 4. Use `references/discovery-positioning.md` for CompleteTech LLC framing and guardrails. 5. Use `references/discovery-catalog.md` for near-exhaustive artifact templates. 6. Keep discovery practical and bounded. Do not fabricate client facts, proof, savings metrics, regulated-use assurances, legal claims, or implementation feasibility. ## Artifact Selection Guide - First-pass lead fit: use `quick-qualification-checklist`. - New opportunity intake: use `client-intake-questionnaire`. - Live discovery call: use `workflow-discovery-script`. - Multiple roles or departments: use `stakeholder-interview-guide`. - Existing process documentation: use `current-state-workflow-map`. - Proposed reviewed-agent process: use [REDACTED_SECRET]. - System, document, data, or access review: use [REDACTED_SECRET]. - API/tool feasibility: use `tool-api-readiness-checklist`. - Approval and escalation design: use `human-approval-gate-checklist`. - Regulated, sensitive, or risky workflow: use `risk-and-excluded-use-checklist`. - Buyer asks what success looks like: use `success-criteria-worksheet`. - Need test examples: use `evaluation-example-worksheet`. - Decide whether to propose a pilot: use `pilot-readiness-scorecard`. - After discovery call: use `discovery-recap-memo`. - Handoff into proposal/SOW: use [REDACTED_SECRET]. - Missing facts or assumptions: use `assumptions-and-unknowns-log`. - Ownership unclear: use [REDACTED_SECRET]. - Dependencies unclear: use [REDACTED_SECRET]. - Sensitive data or retention concerns: use [REDACTED_SECRET]. - Several possible workflows: use `workflow-prioritization-matrix`. - Need logging/monitoring requirements: use [REDACTED_SECRET]. - Need support/handoff expectations: use [REDACTED_SECRET]. - Need production-readiness check: use [REDACTED_SECRET]. When several artifacts fit, choose the earliest artifact that resolves the biggest unknown. Do not draft proposal/SOW scope until the workflow, owners, approval points, success criteria, dependencies, and exclusions are clear enough to avoid vague scope. ## Quality Rules - Frame discovery as bounded workflow scoping, not AI brainstorming. - Always identify human approval points for external communication, production changes, purchases, data export, and material business decisions. - Capture risks, excluded uses, data sensitivity, and assumptions explicitly. - Make outputs easy to hand to `agentic-proposal-skill`. - Use `TBD` or open questions for unknowns. ## Resource Guide - `references/discovery-positioning.md`: load for CompleteTech LLC discovery language and boundaries. - `references/use-case-decision-table.md`: load when choosing an artifact. - `references/discovery-lifecycle.md`: load for flow from lead qualification through proposal handoff. - `references/discovery-catalog.md`: load for the near-exhaustive artifact library. - `references/template-index.json`: machine-readable template metadata used by the renderer. - `scripts/render_discovery.py`: list discovery artifacts or render a draft with placeholders. ## Renderer ```bash python3 scripts/render_discovery.py --list python3 scripts/render_discovery.py --stage readiness --list python3 scripts/render_discovery.py --template client-intake-questionnaire --var client_name=Acme --var workflow="support triage" ``` Rendered artifacts are drafts. Replace placeholders with verified client facts and refine questions for the meeting context. ## Rendering to a Branded PDF Artifacts from this skill are delivered as branded CompleteTech LLC **PDF** documents, not raw Markdown. The renderer emits the PDF (and prints the Markdown) in **one command**, using the same reportlab branding engine as the contract skill: ```bash pip install -r requirements.txt python3 scripts/render_discovery.py --template requirements-brief-for-proposal-sow-handoff \ --out artifact.pdf --png artifact.png \ --title "Requirements Brief — Proposal / SOW Handoff" --doc-type "DISCOVERY HANDOFF" \ --subtitle "Prepared for <b>Northwind Trading Co.</b>" --meta "DOCUMENT NO.=DISC-2026-0117" --meta "DATE=2026-05-15" \ --var client_name="Client Name" --var workflow="support triage" ``` - `--no-pdf` emits Markdown only (the original behavior); `--no-cover` drops the cover page. - Already drafted the Markdown yourself? Render it directly: `python3 scripts/render_pdf.py --markdown artifact.md --out artifact.pdf --logo assets/logo.png --title "..."`. - The PDF supports a Markdown subset: `#`/`##`/`###` headings, paragraphs, `-` bullets, tables, `>` callouts, `**bold**`, and `[PAGE_BREAK]`. PDF requires `reportlab`; the optional `--png` preview requires `pypdfium2` and `pillow`. See `assets/examples/` for a rendered example. ## Network Boundary This skill is local-only. It does not include outbound network helpers, callbacks, or any helper that posts discovery run metadata to an external service.

path: agents/openai.yaml
content: interface:
  display_name: "Agentic Discovery Skill"
  short_description: "Scope agentic workflow discovery"
  default_prompt: "Use $agentic-discovery-skill to choose and draft the right discovery artifact for an agentic development opportunity."

policy:
  allow_implicit_invocation: false


path: assets/examples/example.md
content: # Requirements Brief — Proposal / SOW Handoff

This brief packages verified discovery facts for the Customer Support Email Triage Agent opportunity at Northwind Trading Co. It is the handoff into proposal/SOW scoping. It is not a proposal, contract, or launch approval.

## 1. Opportunity Summary

Northwind Trading Co. runs a shared support inbox that receives roughly 850 customer emails per day across order status, returns, billing, and product questions. Two senior agents triage and route every message by hand before specialists reply, creating a 6–9 hour first-response lag during peak weeks.

| Field | Verified Fact |
|---|---|
| Client | Northwind Trading Co. (wholesale distribution) |
| Sponsor | Dana Whitfield, VP Customer Operations |
| Workflow | Inbound support email triage, drafting, and routing |
| Daily volume | ~850 emails/day; ~1,400 on Monday peaks |
| Current owners | 2 senior agents rotate triage duty |
| Primary pain | 6–9 hour first-response lag; inconsistent routing |

## 2. Current-State Workflow

- Email lands in a shared Outlook inbox monitored during business hours.
- A senior agent reads each message, labels it, and forwards it to one of five queues.
- Specialists draft replies from memory or by searching an aging help-center wiki.
- No structured logging of categories, volumes, or reply time exists today.

## 3. Proposed Future-State (for proposal scoping)

- An agent classifies each inbound email, drafts a suggested reply grounded in approved help-center content, and recommends a routing queue.
- A human support agent reviews, edits, and approves every customer-facing reply before send.
- All classifications, drafts, and overrides are logged for evaluation and monitoring.

## 4. Systems & Data Readiness

| Item | Status | Notes |
|---|---|---|
| Mailbox access | Available | Sandbox mailbox can be provisioned for the pilot |
| Help-center content | Partial | ~120 articles; ~30 are stale and need exclusion |
| Historical labels | Missing | No labeled triage history; must build a test set |
| PII in emails | Present | Names, order numbers, partial addresses |

## 5. Human Approval Gates

- Required before any customer-facing reply is sent.
- Required before escalation to a named specialist or manager.
- Required before any refund, credit, or goodwill offer is suggested to a customer.

## 6. Risks & Excluded Uses

- Excluded: autonomous sending without human review.
- Excluded: handling of payment card data or full account credentials.
- Risk: prompt injection via crafted inbound email content — must be tested.
- Risk: stale help-center articles producing incorrect guidance.

## 7. Draft Success Criteria

- Routing accuracy at or above 90% on a held-out labeled test set.
- Median first-response preparation time reduced from hours to minutes.
- Zero customer-facing replies sent without human approval during the pilot.

## 8. Open Questions & Assumptions

> Open: Which five queues are in scope, and who owns each? Assumed the existing Outlook routing taxonomy until confirmed.

- Assumption: a non-production sandbox mailbox is acceptable for the pilot.
- Assumption: legal will approve use of de-identified historical emails to build the test set.
- Open: who is the approver for excluded-use and data-boundary decisions?

## 9. Downstream Handoff

A proposal can scope an 8-week bounded pilot only after queue ownership, the approved help-center subset, data boundaries, and excluded uses are confirmed. Route data-sensitivity and prompt-injection concerns to the security-review skill before launch.


path: BRAND_ASSETS.md
content: # Brand Assets

CompleteTech LLC names, logos, seals, and brand assets included in this repository are not licensed under the MIT License.

They remain trademarks, service marks, or brand assets of CompleteTech LLC and may not be reused in a way that suggests endorsement, affiliation, sponsorship, or ownership without written permission.

The logo is included so this repository can identify itself as part of the CompleteTech LLC agentic services skill library.


path: CLAW_HUB_PUBLISHING.md
content: # ClawHub Publishing

This repository is prepared for ClawHub publishing as a text-based OpenClaw skill bundle.

## Included In ClawHub

The ClawHub bundle is intended to include text-based skill material only:

- `SKILL.md`, `README.md`, `QUALITY.md`, and this file
- `agents/openai.yaml`
- `pyproject.toml`
- `.github/workflows/quality.yml`
- `scripts/*.py`
- `references/` text files, schemas, catalogs, and examples
- `examples/` text inputs such as `.ini` files or README placeholders
- `assets/diagrams/*.mmd`
- config examples and templates where they are text-based

## Excluded From ClawHub

`.clawhubignore` excludes binary and generated assets from the publish candidate, including PDFs, PNG previews, DOCX files, fonts, logos, `preview/`, `output/`, caches, virtual environments, local env files, and temporary files.

Those files remain part of the GitHub repository for brand presentation, examples, local demos, and generated artifact previews. They are not part of the ClawHub text bundle.

## License And Brand Boundary

ClawHub publishes skills under MIT-0. The text/code bundle can be used under ClawHub's publishing terms, but CompleteTech LLC names, logos, seals, and other brand assets remain reserved. Publishing this text bundle does not grant a trademark or brand-asset license and does not relicense excluded binary brand assets.

## Runtime Dependencies

Runtime requirements are declared in `SKILL.md` under `metadata.openclaw`.

- All Python-backed skills require `python3`.
- PDF/generator skills declare `reportlab` where PDF rendering is used.
- The contract skill declares `jinja2`.
- `pyyaml` is declared so the included quality/audit validator can parse YAML metadata.
- Optional PNG preview dependencies such as `pypdfium2` and `pillow` are GitHub/local-demo conveniences, not required for the ClawHub core workflow unless a user intentionally runs PNG preview generation.

## Local Readiness Check

Run before publishing:

```bash
python3 scripts/validate_quality.py
```

The validator checks lint, Python compilation, structured-file parsing, Mermaid rendering, smoke tests, Pyright where configured, and ClawHub bundle readiness. It does not publish to ClawHub.

## Publishing

Do not publish automatically. Use the ClawHub CLI only after explicit approval and an authenticated owner context, for example:

```bash
clawhub skill publish . --owner <owner> --version <semver>
```


path: examples/README.md
content: # Examples

This directory is reserved for runnable example inputs, overrides, or notes for this skill.

Rendered demonstration artifacts live under `assets/examples/` so README previews and packaged outputs stay close to the visual assets they reference.


path: LICENSE
content: MIT License

Copyright (c) 2026 CompleteTech LLC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


path: pyproject.toml
content: [tool.ruff]
line-length = 120
target-version = "py312"
exclude = [
  ".git",
  ".venv",
  "venv",
  "env",
  "ENV",
  "output",
  "preview",
]

[tool.ruff.lint]
select = ["E4", "E7", "E9", "F"]


path: QUALITY.md
content: # Quality Checks

Run the production-readiness checks from this repository root:

```bash
python3 scripts/validate_quality.py
```

The validator compiles Python files, runs Ruff, parses YAML/JSON/INI files, renders Mermaid sources when Mermaid tooling is available, runs generator `--help` smoke checks where generator scripts exist, runs catalog `--list` smoke checks where renderer catalog scripts exist, and runs Pyright when a `pyrightconfig.json` file is present.

GitHub Actions runs the same validator on push and pull request.


path: README.md
content: # Agentic Discovery Skill

<p align="center">
  <img src="assets/logo.png" alt="CompleteTech LLC logo" width="260">
</p>

A CompleteTech LLC Codex skill for creating discovery and scoping artifacts before proposal/SOW creation for agentic development opportunities.

## About

Part of the CompleteTech LLC agentic services skill library. This skill turns early workflow opportunities into verified facts, readiness checks, risk boundaries, success criteria, and proposal handoff material.

## OpenClaw / ClawHub Metadata

- Skill key: `agentic-discovery-skill`
- Version-ready metadata: `1.0.3`
- Homepage: https://github.com/CompleteTech-LLC/agentic-discovery-skill
- README: https://github.com/CompleteTech-LLC/agentic-discovery-skill#readme
- Runtime binaries: `python3`
- Python packages: `reportlab==4.5.1`, `pyyaml==6.0.3` (optional PNG preview: `pypdfium2==5.8.0`, `pillow==12.2.0`)
- Intended registry/discovery tags: `latest`, `complete-tech`, `codex-skill`, `agentic-development`, `agentic-workflows`, `discovery`, `scoping`, `requirements`, `pdf`, `pdf-generator`
- License: repository code, templates, and documentation use MIT; published by CompleteTech on ClawHub.
- Brand assets: CompleteTech LLC names, logos, seals, and brand assets are reserved; see `BRAND_ASSETS.md`.

## Workflow Diagram

Source: [assets/diagrams/workflow.mmd](assets/diagrams/workflow.mmd).


```mermaid
flowchart LR
  A[Lead or workflow idea] --> B[Qualification]
  B --> C[Workflow discovery]
  C --> D[Readiness, risk, and approvals]
  D --> E[Success criteria and examples]
  E --> F{Pilot-ready?}
  F -->|No| G[Assumptions and unknowns]
  F -->|Yes| H[Proposal/SOW handoff brief]
  classDef source fill:#eef6ff,stroke:#3778c2,color:#102a43;
  classDef gate fill:#fff7e6,stroke:#c97a12,color:#3d2600;
  classDef output fill:#eefaf0,stroke:#2f8f46,color:#12351d;
  class A,B,C,D,E source;
  class F gate;
  class G,H output;
```

## What It Does

- Selects the right discovery artifact by situation.
- Drafts intake questionnaires, discovery scripts, interview guides, workflow maps, readiness checklists, approval-gate reviews, risk checks, success criteria, evaluation worksheets, scorecards, recaps, and proposal handoff briefs.
- Helps gather verified facts for the existing agentic email, proposal, contract, invoice, and certificate skills.
- Keeps discovery focused on practical, bounded workflow scoping with human approvals, evaluation, logging, monitoring, documentation, support, and handoff.

## Contents

- `SKILL.md` - operating instructions and artifact-selection guide.
- `references/discovery-catalog.md` - reusable discovery/scoping artifact templates.
- `references/use-case-decision-table.md` - quick guide for choosing the right artifact.
- `references/discovery-lifecycle.md` - flow from qualification through proposal handoff.
- `references/discovery-positioning.md` - CompleteTech LLC discovery language and guardrails.
- `scripts/render_discovery.py` - deterministic template listing and rendering helper.
- `scripts/render_pdf.py` - branded CompleteTech PDF generator (Markdown -> PDF + optional PNG preview).
- `requirements.txt` - Python dependencies for branded PDF rendering.

## Quick Start

```bash
python3 scripts/render_discovery.py --list
python3 scripts/render_discovery.py \
  --template client-intake-questionnaire \
  --var client_name=Acme \
  --var workflow="support triage"
```

Rendered artifacts are drafts. Replace placeholders with verified client, workflow, systems, approval, risk, and success criteria details before use.

## Example

![Requirements Brief — Proposal / SOW Handoff preview](assets/examples/example.png)

Example files: [Markdown](assets/examples/example.md) · [PDF](assets/examples/example.pdf) · [DOCX](assets/examples/example.docx).

**Discovery handoff brief: Northwind Trading Co. — Customer Support Email Triage Agent**

- Workflow: hand-triaged support inbox (~850 emails/day) with a 6–9 hour first-response lag.
- Readiness: sandbox mailbox available; help-center subset and labeled test set still needed.
- Gates: human approval before any customer-facing send, escalation, or refund suggestion.
- Downstream: proposal can scope an 8-week pilot once data boundaries and excluded uses are confirmed.

Generate it in one command (branded PDF + Markdown, like the contract skill):

```bash
pip install -r requirements.txt
python3 scripts/render_discovery.py --template requirements-brief-for-proposal-sow-handoff \
  --out assets/examples/example.pdf --png assets/examples/example.png \
  --markdown-out assets/examples/example.md \
  --logo assets/logo.png --title "Requirements Brief — Proposal / SOW Handoff" --doc-type "DISCOVERY HANDOFF" \
  --subtitle "Prepared for <b>Northwind Trading Co.</b>" --meta "DOCUMENT NO.=DISC-2026-0117" --meta "DATE=2026-05-15"
```

The committed `example.{md,pdf,png}` use curated, realistic demonstration data for the Northwind Trading Co. support-triage pilot; pass `--var key=value` to fill template placeholders with your own facts.

## Brand Notes

Use a direct, concrete, low-hype tone. Present discovery as bounded workflow scoping: repeated workflow, inputs, systems, tools, retrieval sources, decision points, human approvals, risks, exclusions, evaluation examples, logging, monitoring, documentation, support, and handoff. Do not invent proof, regulated-use assurances, legal claims, savings metrics, or client facts.

## Network Boundary

This skill is local-only. It does not include outbound network helpers, callbacks, or any helper that posts discovery run metadata to an external service.

## License

Code, templates, and documentation are licensed under the MIT License. CompleteTech LLC names, logos, seals, and brand assets are reserved and are not licensed for reuse except to identify this project. See `LICENSE` and `BRAND_ASSETS.md`.


path: references/discovery-catalog.md
content: # Near-Exhaustive Agentic Development Discovery Catalog

Replace placeholders with verified facts. Use `TBD` for unknowns.

## Common Placeholders

- `{client_name}`
- `{workflow}`
- `{stakeholders}`
- `{systems}`
- `{data_sources}`
- `{tools}`
- `{inputs}`
- `{outputs}`
- `{approval_points}`
- `{risks}`
- `{exclusions}`
- `{success_criteria}`
- `{evaluation_examples}`
- `{dependencies}`
- `{owner}`
- `{next_step}`

## Templates

### client-intake-questionnaire
Artifact Type: Client Intake Questionnaire

Client: {client_name}
Workflow under consideration: {workflow}

Questions:
1. What repeated workflow should we examine first?
2. What starts the workflow?
3. Who owns the workflow?
4. Which systems, documents, inboxes, tickets, or tools are involved?
5. What decisions are made by people today?
6. What actions require approval?
7. What data is sensitive or restricted?
8. What would make a pilot useful?
9. What timeline or business trigger matters?
10. Who must approve the next step?

### workflow-discovery-script
Artifact Type: Workflow Discovery Script

Opening:
The goal is to understand {workflow} well enough to decide whether a bounded agentic pilot is worth proposing.

Sections:
1. Current trigger and inputs: {inputs}
2. Current steps and handoffs
3. Systems and source-of-truth documents: {systems}
4. Human decisions and approvals: {approval_points}
5. Common edge cases
6. Risks and excluded uses: {risks}
7. Evaluation examples and success criteria
8. Next step: {next_step}

### stakeholder-interview-guide
Artifact Type: Stakeholder Interview Guide

Stakeholders:
{stakeholders}

Operator questions:
- What work repeats most often?
- Where do delays or rework happen?
- What context is hard to find?

Reviewer questions:
- What must you approve?
- What makes a draft acceptable?
- What requires escalation?

Technical owner questions:
- Which systems and APIs are available?
- What permissions are needed?
- What logging and retention rules apply?

Decision maker questions:
- What business outcome matters?
- What risks would block approval?
- What evidence would justify a pilot?

### current-state-workflow-map
Artifact Type: Current-State Workflow Map

Workflow: {workflow}

Current trigger:
{inputs}

Current steps:
1. {step_1}
2. {step_2}
3. {step_3}

Systems/tools:
{systems}

Decision points:
{decision_points}

Pain points:
{pain_points}

Known exceptions:
{exceptions}

### future-state-agentic-workflow-map
Artifact Type: Future-State Agentic Workflow Map

Workflow: {workflow}

Proposed reviewed-agent path:
1. Intake received
2. Agent classifies or extracts key facts
3. Agent retrieves context from approved sources
4. Agent drafts or recommends next action
5. Human reviews and approves where required
6. Approved action is taken
7. Result and rationale are logged

Agent responsibilities:
{agent_responsibilities}

Human approval points:
{approval_points}

Logs/monitoring:
{logging_needs}

### systems-and-data-access-checklist
Artifact Type: Systems and Data Access Checklist

Systems:
{systems}

Data sources:
{data_sources}

Check:
- system owner identified
- access path known
- sandbox/test environment available
- sample inputs available
- source-of-truth rules known
- data sensitivity understood
- retention expectations known
- export restrictions known

Open access issues:
{dependencies}

### tool-api-readiness-checklist
Artifact Type: Tool/API Readiness Checklist

Tools/APIs:
{tools}

Check:
- API documentation available
- authentication method known
- permission scope understood
- rate limits known
- test credentials available
- write actions can be disabled or reviewed
- audit logs available
- rollback or correction path known

Readiness notes:
{notes}

### human-approval-gate-checklist
Artifact Type: Human Approval Gate Checklist

Workflow: {workflow}

Require human approval before:
- external communication
- production change
- purchase or financial action
- data export
- account, permission, or security change
- material business decision
- regulated or sensitive action

Specific approval points:
{approval_points}

Reviewer roles:
{reviewer_roles}

### risk-and-excluded-use-checklist
Artifact Type: Risk and Excluded-Use Checklist

Risks to assess:
- sensitive data
- incorrect or incomplete output
- unauthorized tool use
- missing approval
- poor source retrieval
- production impact
- legal/regulatory constraints

Excluded uses:
{exclusions}

Mitigations:
{mitigations}

### success-criteria-worksheet
Artifact Type: Success Criteria Worksheet

Workflow: {workflow}

A successful pilot should prove:
- the workflow can be mapped clearly
- approved sources can be retrieved
- drafts/recommendations are reviewable
- approval gates are practical
- logs capture material steps
- users can operate the workflow after handoff

Specific criteria:
{success_criteria}

### evaluation-example-worksheet
Artifact Type: Evaluation Example Worksheet

Workflow: {workflow}

Representative examples:
{evaluation_examples}

For each example capture:
- input
- expected classification
- relevant source context
- expected draft/recommendation
- required approval
- expected log entry
- failure modes

### pilot-readiness-scorecard
Artifact Type: Pilot Readiness Scorecard

Score each 1-5:
- repeated workflow clarity
- business value
- system/data access
- source-of-truth clarity
- approval gate clarity
- evaluation example availability
- risk manageability
- stakeholder ownership

Recommendation:
{next_step}

Notes:
{notes}

### discovery-recap-memo
Artifact Type: Discovery Recap Memo

Client: {client_name}
Workflow: {workflow}

What we learned:
{current_state}

Pain points:
{pain_points}

Systems/data:
{systems}

Approval/risk notes:
{approval_points}
{risks}

Recommended next step:
{next_step}

### requirements-brief-for-proposal-sow-handoff
Artifact Type: Requirements Brief for Proposal/SOW Handoff

Client: {client_name}
Workflow: {workflow}
Owner: {owner}

Recommended scope:
{recommended_scope}

Deliverables to propose:
{deliverables}

Success criteria:
{success_criteria}

Assumptions:
{assumptions}

Exclusions:
{exclusions}

Dependencies:
{dependencies}

### assumptions-and-unknowns-log
Artifact Type: Assumptions and Unknowns Log

Known facts:
{known_facts}

Assumptions:
{assumptions}

Unknowns:
{unknowns}

Owner for answers:
{owner}

Deadline:
{deadline}

### stakeholder-responsibility-matrix
Artifact Type: Stakeholder Responsibility Matrix

| Area | Client owner | CompleteTech LLC role | Notes |
|---|---|---|---|
| Workflow ownership | {workflow_owner} | Discovery/scoping | {notes} |
| Systems access | {technical_owner} | Access requirements | {notes} |
| Review/approval | {review_owner} | Approval model design | {notes} |
| Business decision | {decision_maker} | Proposal recommendation | {notes} |

### implementation-dependency-checklist
Artifact Type: Implementation Dependency Checklist

Dependencies:
- signed scope or written approval
- project owner
- reviewer list
- sample inputs
- system access
- source documents
- API/tool credentials
- approval rules
- evaluation examples
- logging/retention requirements

Open dependencies:
{dependencies}

### data-sensitivity-and-retention-worksheet
Artifact Type: Data Sensitivity and Retention Worksheet

Data involved:
{data_sources}

Sensitivity categories:
- public
- internal
- confidential
- regulated or restricted
- credentials/secrets

Retention expectations:
{retention}

Handling requirements:
{handling_requirements}

### workflow-prioritization-matrix
Artifact Type: Workflow Prioritization Matrix

Score each candidate 1-5:
- repeatability
- business value
- pain/urgency
- data readiness
- tool readiness
- approval clarity
- risk manageability
- pilot size

Candidate workflows:
{candidate_workflows}

Recommended first workflow:
{workflow}

### quick-qualification-checklist
Artifact Type: Quick Qualification Checklist

Qualify if:
- workflow repeats often
- inputs are identifiable
- source context exists
- outputs are reviewable
- approval points are clear or discoverable
- risk is manageable
- owner exists
- buyer has a reason to act

Disqualify or defer if:
- workflow is one-off
- final decision is regulated or safety-critical without separate review
- no owner exists
- no sample inputs are available
- scope is too broad for a pilot

Recommendation:
{next_step}

### logging-and-monitoring-needs-worksheet
Artifact Type: Logging and Monitoring Needs Worksheet

Workflow: {workflow}

Log:
- inputs received
- retrieval sources used
- draft/recommendation
- tool calls proposed or made
- reviewer approval/rejection
- final action
- errors and escalations

Monitoring needs:
{monitoring_needs}

### support-and-handoff-discovery-worksheet
Artifact Type: Support and Handoff Discovery Worksheet

Post-delivery expectations:
- who operates the workflow?
- who reviews outputs?
- who handles exceptions?
- who updates source documents?
- who monitors logs?
- what support window is expected?

Support/handoff notes:
{support_expectations}

### pilot-to-production-readiness-checklist
Artifact Type: Pilot-to-Production Readiness Checklist

Check:
- pilot accepted
- evaluation examples passed
- approval gates confirmed
- production permissions reviewed
- monitoring/logging ready
- support owner assigned
- rollback/correction path known
- documentation complete
- training complete
- excluded uses documented

Production readiness recommendation:
{next_step}


path: references/discovery-lifecycle.md
content: # Agentic Development Discovery Lifecycle

## Flow

1. Quick qualification
   - Decide whether there is a repeated workflow worth scoping.

2. Client intake
   - Gather business context, workflow owner, systems, timeline, and constraints.

3. Stakeholder discovery
   - Interview operators, reviewers, technical owners, and decision makers.

4. Current-state mapping
   - Document inputs, steps, handoffs, systems, decisions, and pain points.

5. Future-state agentic workflow design
   - Identify retrieval, drafting, tool routing, approvals, logs, and monitoring.

6. Readiness and risk review
   - Check data, APIs, permissions, sensitivity, exclusions, and dependencies.

7. Evaluation and success criteria
   - Define representative examples and acceptance measures.

8. Pilot readiness and handoff
   - Decide whether to recommend assessment, pilot, POC, proposal, or no-go.

## Handoff To Other Skills

- `agentic-email-skill`: use discovery facts for follow-up and proposal-send emails.
- `agentic-proposal-skill`: use recap, requirements brief, scorecard, and success criteria to draft proposal/SOW.
- `agentic-contract-skill`: use approved scope, assumptions, exclusions, acceptance criteria, and support terms.
- `agentic-invoice-skill`: use pricing model, milestones, deposit, retainer, and change-order triggers.
- `agentic-certificate-skill`: use only if training or attendance certificates are included.

## Minimum Handoff Facts

- workflow name
- client owner and reviewer
- current pain
- current systems/tools
- proposed agent actions
- human approval gates
- success criteria
- evaluation examples
- assumptions
- exclusions
- dependencies
- recommended next step


path: references/discovery-positioning.md
content: # CompleteTech LLC Discovery Positioning

## Discovery Frame

CompleteTech LLC agentic development discovery is practical workflow scoping. The goal is to find one repeated workflow that can be made more reliable with tool routing, retrieval, draft generation, approval gates, logs, monitoring, documentation, and handoff.

## What To Learn

- repeated workflow and business owner
- trigger/input that starts the work
- current steps and handoffs
- systems, tools, documents, APIs, and data sources
- decisions made by people today
- actions that require human approval
- retrieval sources and source-of-truth rules
- data sensitivity and retention constraints
- risks and excluded uses
- evaluation examples and success criteria
- logging and monitoring expectations
- documentation, training, support, and handoff needs

## Language To Use

Use:

- "bounded workflow scoping"
- "reviewed agent workflow"
- "human approval gates"
- "evaluation examples"
- "systems and data readiness"
- "proposal/SOW handoff brief"

Avoid:

- "fully autonomous business decisions"
- "replace your staff"
- invented ROI or savings
- regulated-use assurances
- legal, medical, financial, employment, housing, insurance, credit, biometric, surveillance, or safety-critical final-decision claims

## Proof Rules

Do not invent proof. During discovery, proof is replaced by evidence-gathering:

- sample inputs
- representative edge cases
- workflow volume
- current turnaround time if supplied
- error/rework examples
- reviewer feedback
- acceptance examples

## Output Standard

A good discovery artifact should make it easier to draft a proposal. It should clearly state:

- what is known
- what is unknown
- what the recommended next artifact is
- what must be excluded or handled by human approval


path: references/template-index.json
content: {
  "templates": [
    {"id": "client-intake-questionnaire", "stage": "intake", "type": "questionnaire"},
    {"id": "workflow-discovery-script", "stage": "discovery", "type": "script"},
    {"id": "stakeholder-interview-guide", "stage": "discovery", "type": "guide"},
    {"id": "current-state-workflow-map", "stage": "mapping", "type": "map"},
    {"id": "future-state-agentic-workflow-map", "stage": "mapping", "type": "map"},
    {"id": "systems-and-data-access-checklist", "stage": "readiness", "type": "checklist"},
    {"id": "tool-api-readiness-checklist", "stage": "readiness", "type": "checklist"},
    {"id": "human-approval-gate-checklist", "stage": "risk", "type": "checklist"},
    {"id": "risk-and-excluded-use-checklist", "stage": "risk", "type": "checklist"},
    {"id": "success-criteria-worksheet", "stage": "evaluation", "type": "worksheet"},
    {"id": "evaluation-example-worksheet", "stage": "evaluation", "type": "worksheet"},
    {"id": "pilot-readiness-scorecard", "stage": "readiness", "type": "scorecard"},
    {"id": "discovery-recap-memo", "stage": "handoff", "type": "memo"},
    {"id": "requirements-brief-for-proposal-sow-handoff", "stage": "handoff", "type": "brief"},
    {"id": "assumptions-and-unknowns-log", "stage": "tracking", "type": "log"},
    {"id": "stakeholder-responsibility-matrix", "stage": "planning", "type": "matrix"},
    {"id": "implementation-dependency-checklist", "stage": "readiness", "type": "checklist"},
    {"id": "data-sensitivity-and-retention-worksheet", "stage": "risk", "type": "worksheet"},
    {"id": "workflow-prioritization-matrix", "stage": "qualification", "type": "matrix"},
    {"id": "quick-qualification-checklist", "stage": "qualification", "type": "checklist"},
    {"id": "logging-and-monitoring-needs-worksheet", "stage": "operations", "type": "worksheet"},
    {"id": "support-and-handoff-discovery-worksheet", "stage": "operations", "type": "worksheet"},
    {"id": "pilot-to-production-readiness-checklist", "stage": "rollout", "type": "checklist"}
  ]
}


path: references/use-case-decision-table.md
content: # Discovery Use-Case Decision Table

| Situation | Template | Why |
|---|---|---|
| First-pass lead fit | `quick-qualification-checklist` | Determines whether discovery is worth doing. |
| New opportunity intake | `client-intake-questionnaire` | Gathers baseline business and workflow facts. |
| Live discovery call | `workflow-discovery-script` | Structures the conversation. |
| Multiple roles involved | `stakeholder-interview-guide` | Tailors questions by stakeholder group. |
| Existing process unclear | `current-state-workflow-map` | Documents current inputs, steps, systems, and handoffs. |
| Designing proposed workflow | `future-state-agentic-workflow-map` | Defines reviewed-agent path. |
| Access/data readiness | `systems-and-data-access-checklist` | Checks systems, documents, and permissions. |
| API/tool feasibility | `tool-api-readiness-checklist` | Checks integration constraints. |
| Approval model unclear | `human-approval-gate-checklist` | Identifies decisions requiring human review. |
| Sensitive or regulated concern | `risk-and-excluded-use-checklist` | Captures risk and excluded uses. |
| Buyer asks what success means | `success-criteria-worksheet` | Defines acceptance and outcome measures. |
| Need test cases | `evaluation-example-worksheet` | Captures representative examples. |
| Decide whether to propose pilot | `pilot-readiness-scorecard` | Scores readiness and recommends next step. |
| After discovery | `discovery-recap-memo` | Summarizes findings. |
| Handoff to proposal/SOW | `requirements-brief-for-proposal-sow-handoff` | Packages scope inputs for proposal skill. |
| Missing facts | `assumptions-and-unknowns-log` | Tracks unknowns and assumptions. |
| Ownership unclear | `stakeholder-responsibility-matrix` | Assigns accountable parties. |
| Dependencies unclear | `implementation-dependency-checklist` | Lists blockers and prerequisites. |
| Data sensitivity/retention | `data-sensitivity-and-retention-worksheet` | Captures privacy and retention needs. |
| Several workflows compete | `workflow-prioritization-matrix` | Ranks candidate workflows. |
| Logging/monitoring requirements | `logging-and-monitoring-needs-worksheet` | Captures observability needs. |
| Support/handoff expectations | `support-and-handoff-discovery-worksheet` | Captures post-delivery expectations. |
| Production readiness | `pilot-to-production-readiness-checklist` | Checks rollout requirements. |

Selection rule: choose the artifact that resolves the most important uncertainty blocking a proposal. If workflow fit is unclear, qualify first. If scope is unclear, map current/future state. If risk is unclear, run approval/risk/data readiness checks. If enough facts are known, create the requirements brief.


path: requirements.txt
content: # Branded PDF artifact rendering (scripts/render_pdf.py)
reportlab==4.5.1
pyyaml==6.0.3
# Optional: only needed to also emit a PNG preview montage (scripts/render_pdf.py --png)
pypdfium2==5.8.0
pillow==12.2.0


path: scripts/render_discovery.py
content: #!/usr/bin/env python3
"""List and render agentic development discovery artifacts."""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
CATALOG_MD = ROOT / "references" / "discovery-catalog.md"
INDEX_JSON = ROOT / "references" / "template-index.json"


def load_index() -> list[dict[str, str]]:
    data = json.loads(INDEX_JSON.read_text(encoding="utf-8"))
    return data["templates"]


def extract_template(template_id: str) -> str:
    text = CATALOG_MD.read_text(encoding="utf-8")
    pattern = re.compile(
        rf"^### {re.escape(template_id)}\n(?P<body>.*?)(?=^### |\Z)",
        re.MULTILINE | re.DOTALL,
    )
    match = pattern.search(text)
    if not match:
        raise KeyError(f"Template not found in discovery-catalog.md: {template_id}")
    return match.group("body").strip()


class SafeDict(dict[str, str]):
    def __missing__(self, key: str) -> str:
        return "{" + key + "}"


def parse_vars(raw_vars: list[str]) -> dict[str, str]:
    values: dict[str, str] = {}
    for raw in raw_vars:
        if "=" not in raw:
            raise ValueError(f"--var must be key=value, got: {raw}")
        key, value = raw.split("=", 1)
        key = key.strip()
        if not key:
            raise ValueError(f"--var key cannot be empty: {raw}")
        values[key] = value
    return values


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--list", action="store_true", help="List available discovery artifact IDs.")
    parser.add_argument("--stage", help="Filter --list by stage.")
    parser.add_argument("--type", dest="artifact_type", help="Filter --list by type.")
    parser.add_argument("--template", help="Artifact ID to render.")
    parser.add_argument("--var", action="append", default=[], help="Placeholder value as key=value.")
    parser.add_argument("--out", default=None,
                        help="Branded PDF output path (default: output/<template>.pdf). "
                             "Same reportlab branding as the contract skill.")
    parser.add_argument("--markdown-out", default=None, help="Also write the filled Markdown here.")
    parser.add_argument("--png", default=None, help="Optional PNG preview montage path.")
    parser.add_argument("--no-pdf", action="store_true", help="Emit Markdown only; skip PDF.")
    parser.add_argument("--no-cover", action="store_true", help="Skip the PDF cover page.")
    parser.add_argument("--title", default=None, help="PDF title (defaults to the template subject/id).")
    parser.add_argument("--doc-type", default=None, help="PDF doc-type label (defaults to the template stage).")
    parser.add_argument("--subtitle", default="", help="Cover subtitle, e.g. \"Prepared for <b>Client</b>\".")
    parser.add_argument("--logo", default=None, help="Logo path (defaults to assets/logo.png).")
    parser.add_argument("--meta", action="append", default=[], help="Cover/letterhead chip as LABEL=VALUE.")
    parser.add_argument("--watermark", default="DEMO DRAFT", help="Watermark text (empty to disable).")
    parser.add_argument("--footer", default="CompleteTech LLC - demonstration artifact", help="Footer text.")
    args = parser.parse_args()

    templates = load_index()
    if args.list:
        for item in templates:
            if args.stage and item["stage"] != args.stage:
                continue
            if args.artifact_type and item["type"] != args.artifact_type:
                continue
            print(f"{item['id']}\t{item['stage']}\t{item['type']}")
        return 0

    if not args.template:
        parser.error("provide --list or --template")

    ids = {item["id"] for item in templates}
    if args.template not in ids:
        print(f"Unknown template: {args.template}", file=sys.stderr)
        return 2

    values = parse_vars(args.var)
    rendered = extract_template(args.template).format_map(SafeDict(values))
    print(rendered)

    if args.no_pdf:
        return 0

    # Branded PDF output: same reportlab engine and CompleteTech branding as the
    # contract skill (see scripts/render_pdf.py). One command -> Markdown + PDF.
    from datetime import date
    here = Path(__file__).resolve().parent
    sys.path.insert(0, str(here))
    try:
        from render_pdf import build_pdf, montage
    except ImportError as exc:
        print(f"[skip PDF] {exc}; run 'pip install -r requirements.txt' to enable PDF.", file=sys.stderr)
        return 0

    item = next((t for t in templates if t["id"] == args.template), {})
    meta = []
    for entry in args.meta:
        if "=" in entry:
            k, v = entry.split("=", 1)
            meta.append((k.strip(), v.strip()))
    if not meta:
        meta = [("REFERENCE", args.template.upper()), ("DATE", date.today().isoformat())]
    title = args.title or item.get("subject") or item.get("title") or args.template.replace("-", " ").title()
    doc_type = args.doc_type if args.doc_type is not None else str(item.get("stage", "")).replace("_", " ").upper()
    logo = Path(args.logo) if args.logo else (ROOT / "assets" / "logo.png")
    out_pdf = Path(args.out) if args.out else (ROOT / "output" / f"{args.template}.pdf")
    out_pdf.parent.mkdir(parents=True, exist_ok=True)
    if args.markdown_out:
        md_out = Path(args.markdown_out)
        md_out.parent.mkdir(parents=True, exist_ok=True)
        md_out.write_text(rendered, encoding="utf-8")
    cfg = {
        "logo": logo if logo.exists() else None,
        "title": title, "eyebrow": "CompleteTech LLC", "doc_type": doc_type,
        "subtitle": args.subtitle, "meta": meta, "doc_id": meta[0][1] if meta else "",
        "watermark": args.watermark, "footer": args.footer,
        "disclaimer": "Demonstration artifact \u2014 replace placeholders with verified facts before use.",
        "cover": not args.no_cover,
    }
    build_pdf(rendered, cfg, out_pdf)
    print(f"PDF: {out_pdf}", file=sys.stderr)
    if args.png:
        montage(out_pdf, Path(args.png))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)