Stats
Actions
Tags
From shannon
Create optimized prompts for Claude-to-Claude pipelines with research, planning, and execution stages. Use when building prompts that produce outputs for other prompts to consume, or when running multi-stage workflows (research -> plan -> implement).
How this skill is triggered — by the user, by Claude, or both
Slash command
/shannon:create-meta-promptsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<objective>
references/_deepen-prompt-plan-confidence-scoring.mdreferences/_deepen-prompt-plan-deepening-patterns.mdreferences/_deepen-prompt-plan-research-strategies.mdreferences/do-patterns.mdreferences/intelligence-rules.mdreferences/metadata-guidelines.mdreferences/plan-patterns.mdreferences/question-bank.mdreferences/refine-patterns.mdreferences/research-patterns.mdreferences/summary-template.mdEvery execution produces a SUMMARY.md for quick human scanning without reading full outputs.
Each prompt gets its own folder in .prompts/ with its output artifacts, enabling clear provenance and chain detection.
<quick_start>
.prompts/{number}-{topic}-{purpose}/<folder_structure>
.prompts/
├── 001-auth-research/
│ ├── completed/
│ │ └── 001-auth-research.md # Prompt (archived after run)
│ ├── auth-research.md # Full output (XML for Claude)
│ └── SUMMARY.md # Executive summary (markdown for human)
├── 002-auth-plan/
│ ├── completed/
│ │ └── 002-auth-plan.md
│ ├── auth-plan.md
│ └── SUMMARY.md
├── 003-auth-implement/
│ ├── completed/
│ │ └── 003-auth-implement.md
│ └── SUMMARY.md # Do prompts create code elsewhere
├── 004-auth-research-refine/
│ ├── completed/
│ │ └── 004-auth-research-refine.md
│ ├── archive/
│ │ └── auth-research-v1.md # Previous version
│ └── SUMMARY.md
</folder_structure> </quick_start>
Prompts directory: !`[ -d ./.prompts ] && echo "exists" || echo "missing"` Existing research/plans: !`find ./.prompts -name "*-research.md" -o -name "*-plan.md" 2>/dev/null | head -10` Next prompt number: !`ls -d ./.prompts/*/ 2>/dev/null | wc -l | xargs -I {} expr {} + 1`<automated_workflow>
<step_0_intake_gate>
Adaptive Requirements Gathering<critical_first_action> BEFORE analyzing anything, check if context was provided.
IF no context provided (skill invoked without description): → IMMEDIATELY use AskUserQuestion with:
After selection, ask: "Describe what you want to accomplish" (they select "Other" to provide free text).
IF context was provided: → Check if purpose is inferable from keywords:
implement, build, create, fix, add, refactor → Doplan, roadmap, approach, strategy, decide, phases → Planresearch, understand, learn, gather, analyze, explore → Researchrefine, improve, deepen, expand, iterate, update → Refine→ If unclear, ask the Purpose question above as first contextual question → If clear, proceed to adaptive_analysis with inferred purpose </critical_first_action>
<adaptive_analysis> Extract and infer:
auth, stripe-payments)If topic identifier not obvious, ask:
For Refine purpose, also identify target output from .prompts/*/ to improve.
</adaptive_analysis>
<chain_detection>
Scan .prompts/*/ for existing *-research.md and *-plan.md files.
If found:
Match by topic keyword when possible (e.g., "auth plan" → suggest auth-research.md). </chain_detection>
<contextual_questioning> Generate 2-4 questions using AskUserQuestion based on purpose and gaps.
Load questions from: references/question-bank.md
Route by purpose:
<decision_gate> After receiving answers, present decision gate using AskUserQuestion:
Loop until "Proceed" selected. </decision_gate>
After "Proceed" selected, state confirmation:"Creating a {purpose} prompt for: {topic} Folder: .prompts/{number}-{topic}-{purpose}/ References: {list any chained files}"
Then proceed to generation. </step_0_intake_gate>
<step_1_generate>
Generate PromptLoad purpose-specific patterns:
Load intelligence rules: references/intelligence-rules.md
<prompt_structure> All generated prompts include:
For Research and Plan prompts, output must include:
<confidence> - How confident in findings<dependencies> - What's needed to proceed<open_questions> - What remains uncertain<assumptions> - What was assumedAll prompts must create SUMMARY.md with:
<file_creation>
.prompts/{number}-{topic}-{purpose}/completed/ subfolder.prompts/{number}-{topic}-{purpose}/{number}-{topic}-{purpose}.md.prompts/{number}-{topic}-{purpose}/{topic}-{purpose}.md
</file_creation>
</step_1_generate><step_2_present>
Present Decision TreeAfter saving prompt(s), present inline (not AskUserQuestion):
<single_prompt_presentation>
Prompt created: .prompts/{number}-{topic}-{purpose}/{number}-{topic}-{purpose}.md
What's next?
1. Run prompt now
2. Review/edit prompt first
3. Save for later
4. Other
Choose (1-4): _
</single_prompt_presentation>
<multi_prompt_presentation>
Prompts created:
- .prompts/001-auth-research/001-auth-research.md
- .prompts/002-auth-plan/002-auth-plan.md
- .prompts/003-auth-implement/003-auth-implement.md
Detected execution order: Sequential (002 references 001 output, 003 references 002 output)
What's next?
1. Run all prompts (sequential)
2. Review/edit prompts first
3. Save for later
4. Other
Choose (1-4): _
</multi_prompt_presentation> </step_2_present>
<step_3_execute>
Execution Engine<execution_modes> <single_prompt> Straightforward execution of one prompt.
.prompts/{number}-{topic}-{purpose}/{topic}-{purpose}.mdcompleted/ subfolder<sequential_execution> For chained prompts where each depends on previous output.
<progress_reporting> Show progress during execution:
Executing 1/3: 001-auth-research... ✓
Executing 2/3: 002-auth-plan... ✓
Executing 3/3: 003-auth-implement... (running)
</progress_reporting> </sequential_execution>
<parallel_execution> For independent prompts with no dependencies.
<failure_handling> Unlike sequential, parallel continues even if some fail:
<mixed_dependencies> For complex DAGs (e.g., two parallel research → one plan).
<dependency_detection> <automatic_detection> Scan prompt contents for @ references to determine dependencies:
@.prompts/{number}-{topic}/ patterns<inference_rules> If no explicit @ references found, infer from purpose:
Override with explicit references when present. </inference_rules> </automatic_detection>
<missing_dependencies> If a prompt references output that doesn't exist:
.prompts/*/ (already completed)<confidence><dependencies><open_questions><assumptions><validation_failure> If validation fails:
<failure_handling> <sequential_failure> Stop the chain immediately:
✗ Failed at 2/3: 002-auth-plan
Completed:
- 001-auth-research ✓ (archived)
Failed:
- 002-auth-plan: Output file not created
Not started:
- 003-auth-implement
What's next?
1. Retry 002-auth-plan
2. View error details
3. Stop here (keep completed work)
4. Other
</sequential_failure>
<parallel_failure> Continue others, report all results:
Parallel execution completed with errors:
✓ 001-api-research (archived)
✗ 002-db-research: Validation failed - missing <confidence> tag
✓ 003-ui-research (archived)
What's next?
1. Retry failed prompt (002)
2. View error details
3. Continue without 002
4. Other
</parallel_failure> </failure_handling>
- **Sequential**: Archive each prompt immediately after successful completion - Provides clear state if execution stops mid-chain - **Parallel**: Archive all at end after collecting results - Keeps prompts available for potential retry<archive_operation> Move prompt file to completed subfolder:
mv .prompts/{number}-{topic}-{purpose}/{number}-{topic}-{purpose}.md \
.prompts/{number}-{topic}-{purpose}/completed/
Output file stays in place (not moved). </archive_operation>
<result_presentation> <single_result>
✓ Executed: 001-auth-research
✓ Created: .prompts/001-auth-research/SUMMARY.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Auth Research Summary
**JWT with jose library and httpOnly cookies recommended**
## Key Findings
• jose outperforms jsonwebtoken with better TypeScript support
• httpOnly cookies required (localStorage is XSS vulnerable)
• Refresh rotation is OWASP standard
## Decisions Needed
None - ready for planning
## Blockers
None
## Next Step
Create auth-plan.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What's next?
1. Create planning prompt (auth-plan)
2. View full research output
3. Done
4. Other
Display the actual SUMMARY.md content inline so user sees findings without opening files. </single_result>
<chain_result>
✓ Chain completed: auth workflow
Results:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
001-auth-research
**JWT with jose library and httpOnly cookies recommended**
Decisions: None • Blockers: None
002-auth-plan
**4-phase implementation: types → JWT core → refresh → tests**
Decisions: Approve 15-min token expiry • Blockers: None
003-auth-implement
**JWT middleware complete with 6 files created**
Decisions: Review before Phase 2 • Blockers: None
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
All prompts archived. Full summaries in .prompts/*/SUMMARY.md
What's next?
1. Review implementation
2. Run tests
3. Create new prompt chain
4. Other
For chains, show condensed one-liner from each SUMMARY.md with decisions/blockers flagged. </chain_result> </result_presentation>
<special_cases> <re_running_completed> If user wants to re-run an already-completed prompt:
completed/ subfolder{output}.bak<output_conflicts> If output file already exists:
{filename}.bak<commit_handling> After successful execution:
Exception: If user explicitly requests commit, stage and commit:
<recursive_prompts> If a prompt's output includes instructions to create more prompts:
</automated_workflow>
<reference_guides> Prompt patterns by purpose:
Shared templates:
Supporting references:
<success_criteria> Prompt Creation:
.prompts/ with correct namingExecution (if user chooses to run):
completed/ subfolderResearch Quality (for Research prompts):
Skills merged into this canonical survivor during Shannon v0.1.0 Phase 1 curation. Content preserved for Phase 2 canonical-merge work.
deepen-prompt-planThe input already exists. The question is: "Is this grounded enough for the complexity and risk involved?"
This skill identifies weak sections, runs targeted research for those sections, injects functional validation where missing, and strengthens the document in place — all using proper semantic XML formatting.
<what_this_skill_does>
<what_this_skill_does_not_do>
<essential_principles>
Deepening increases justified confidence. It does not make the document longer for its own sake. If a section is already strong, leave it alone. Every addition must earn its place by closing a specific confidence gap. Focus on the weakest 2-5 sections rather than enriching everything. A plan with 3 rock-solid sections and 2 strengthened weak points is better than a plan where every section got a thin coat of paint. If the document describes something that will be built and run, it must have validation gates. The Iron Rule applies: if the real system doesn't work, fix the real system. Never create mocks, stubs, test doubles, or test files. Every gate must have specific, observable, measurable PASS criteria defined BEFORE execution. Use semantic XML tags for structured content. Tags should be descriptive and self-documenting. Use attributes for metadata. Nest tags to represent hierarchy. This makes documents parseable by both humans and downstream Claude instances.Example:
<task id="1" priority="high">
<description>Create the API endpoint</description>
<validation_gate id="VG-1" blocking="true">
<pass_criteria>HTTP 201 with valid JSON body containing "id" field</pass_criteria>
<evidence_command>curl -s -X POST localhost:3000/api/users | tee evidence/vg1.json | jq .</evidence_command>
</validation_gate>
</task>
</essential_principles>
Phase narration (mandatory): At each phase boundary, tell the user which phase you are entering and what it does. This is NOT optional — the user must always know where they are in the 6-phase process. Keep it to one sentence. Examples:
Accept the document path as an argument, from the conversation context, or by scanning common locations:
# Check common plan/prompt locations
find . -maxdepth 3 -name "*.md" \( -path "*/plans/*" -o -path "*/.planning/*" -o -path "*/.prompts/*" -o -path "*/PLAN.md" -o -path "*/PROMPT.md" \) 2>/dev/null | head -20
If multiple candidates exist, ask the user which document to deepen. Do not proceed without a valid file path.
Read the document completely. If it references an origin document (brief, roadmap, spec), read that too.
Determine the document type:
| Type | Signals | Deepening Focus |
|---|---|---|
| Implementation Plan | Tasks, phases, file paths, verification | Sequencing, validation gates, system impact |
| Prompt / Instructions | Role definition, workflows, output specs | Clarity, edge cases, validation criteria |
| Roadmap | Phases, milestones, dependencies | Phase gate criteria, risk treatment, ordering |
| Research Plan | Questions, sources, methodology | Completeness, source quality, gap coverage |
| Agent Instructions | Tools, workflows, decision trees | Edge case handling, failure modes, validation |
Build a risk profile. These are high-risk signals that warrant deeper treatment:
Not every document needs deepening. Use this heuristic:
If the document is already well-grounded, say so. Recommend moving to execution. If the user insists, do a light pass on at most 1-2 sections.
Map the document into its constituent sections. Look for these or their equivalents:
<section_taxonomy> For Plans:
For Prompts / Instructions:
For Roadmaps:
Collect metadata: which sections exist, which are absent, what references are cited, what validation exists.
For each section, compute a confidence gap score.
Load detailed scoring rubric: references/_deepen-prompt-plan-confidence-scoring.md
Scoring formula per section:
gap_score = trigger_count + risk_bonus + critical_section_bonus
Where:
Selection threshold:
Present the scoring table to the user before proceeding. Transparency about what was selected and why builds trust and lets the user adjust the selection. Show each section with its trigger count, bonuses, total score, and which specific triggers fired. Example:
Confidence Gap Scores:
| Section | Triggers | Risk | Critical | Total | Deepen? |
|-----------------|----------|------|----------|-------|---------|
| Key Decisions | 2 | +1 | +1 | 4 | YES |
| → Decisions stated without tradeoff analysis |
| → Obvious alternatives not addressed |
| Risks | 2 | +1 | +1 | 4 | YES |
| → Risks listed without mitigation |
| → Security risks absent where they obviously apply |
| Validation | 2 | +1 | +1 | 4 | YES |
| → No validation gates present |
| → PASS criteria vague |
| Context | 1 | 0 | 0 | 1 | no |
| Overview | 0 | 0 | 0 | 0 | no |
Ask: "These are the sections I'll deepen. Want to adjust before I proceed?" If the user is running this non-interactively (pipeline, subagent), proceed with the top-scored sections automatically.
For each selected section, choose the smallest useful research approach. Do not research everything — only what closes the identified gap.
Load research strategies: references/_deepen-prompt-plan-research-strategies.md
Research priority order (prefer earlier sources):
Research execution:
Present a compact research summary before proceeding. The user should see what evidence was found and how it will inform the rewrite. Use this format:
<research_summary>
<finding section="Key Decisions" source="OWASP Session Management Cheat Sheet">
JWT with short-lived access tokens + refresh rotation is recommended for stateless APIs.
Impact: Adds rationale and source to D1 decision.
</finding>
<finding section="Risks" source="codebase: src/middleware/logger.ts">
Logging middleware already redacts sensitive fields (line 23).
Impact: Risk R3 mitigation can reference existing safeguard.
</finding>
</research_summary>
Keep it brief — 1-3 lines per finding. The goal is transparency, not a research report. If no research was needed (gap closeable from the document itself), say so and skip.
This phase applies specifically to documents that describe something that will be built and executed. Skip for pure research plans or documentation.
Load deepening patterns: references/_deepen-prompt-plan-deepening-patterns.md
If the document has NO validation gates:
Inject the mock detection preamble at the top:
<mock_detection_protocol>
Before executing any task, check intent:
- Creating .test.*, _test.*, *Tests.*, test_* files → STOP
- Importing mock libraries → STOP
- Creating in-memory databases → STOP
- Adding TEST_MODE or NODE_ENV=test flags → STOP
Fix the REAL system instead. No exceptions.
</mock_detection_protocol>
Then inject validation gates after each task or logical unit:
<validation_gate id="VG-{N}" blocking="true">
<prerequisites>[Dependencies started + health checked]</prerequisites>
<execute>[Real system interaction]</execute>
<capture>[Commands that save output to evidence/ files]</capture>
<pass_criteria>[Specific, observable, measurable — defined NOW not during execution]</pass_criteria>
<review>[READ the evidence: Read tool for images, cat for text, jq for JSON]</review>
<verdict>PASS → next task | FAIL → fix real system → re-run from prerequisites</verdict>
<mock_guard>IF tempted to mock → STOP → fix real system</mock_guard>
</validation_gate>
Append a gate manifest at the end:
<gate_manifest>
<total_gates>{N}</total_gates>
<sequence>VG-1 → VG-2 → ... → VG-N</sequence>
<policy>All gates BLOCKING. No advancement on FAIL.</policy>
<evidence_dir>evidence/</evidence_dir>
<regression>If ANY gate FAILS: fix → re-run from failed gate → do NOT skip</regression>
</gate_manifest>
If the document HAS validation gates:
Audit existing gates against quality standards:
Strengthen any gates that fail these checks.
Strengthen only the selected sections. Keep the document coherent and preserve its overall structure.
Size budget: Deepening should make the document stronger, not bloated. Use these heuristics:
Allowed changes:
<confidence>, <assumptions>, <open_questions> metadata where valuableForbidden changes:
XML formatting guidance: Use semantic XML for structured content. Tags should be self-documenting. Attributes carry metadata. Nest for hierarchy. Keep prose sections as regular markdown — XML is for structured, parseable content only.
<task id="2" depends_on="1" platform="ios">
<description>Implement the authentication flow</description>
<files>Sources/Auth/AuthManager.swift, Sources/Auth/TokenStore.swift</files>
<approach>Follow existing AuthProvider protocol pattern in Sources/Auth/</approach>
<validation_gate id="VG-2" blocking="true">
<pass_criteria>
Simulator screenshot shows login screen → enter credentials →
dashboard appears with user name displayed in nav bar
</pass_criteria>
</validation_gate>
</task>
Before writing the updated document:
Write the updated document in place by default. If the user requests a separate file, append -deepened before .md.
<post_deepening> After writing, present next steps:
If substantive changes were made:
If no substantive changes were warranted:
<reference_index>
All in references/:
<success_criteria> A deepened document succeeds when:
npx claudepluginhub krzemienski/shannon --plugin shannonCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.