Initial commit

skills/prompt-architecting/SKILL.md

@@ -0,0 +1,465 @@
+---
+name: prompt-architecting
+description:
+  "Optimizes or analyzes prompts using proven strategies. Use when user
+  provides a prompt for optimization/analysis, or before you generate any prompt content
+  yourself (commands, skills, agents, docs, instructions). Two modes: OPTIMIZE (returns
+  optimized prompt), CONSULT (analysis only). Trigger phrases: 'optimize prompt',
+  'analyze this prompt', 'make concise'."
+allowed-tools:
+  - Read
+---
+
+# prompt-architecting
+
+Optimizes unstructured prompts into constrained, strategy-driven instructions that prevent over-generation and verbosity.
+
+## When to Use
+
+Trigger phrases: "optimize this prompt", "make instructions concise", "architect this prompt", "what's the best way to prompt for X"
+
+## Your Task
+
+When this skill is used, you are acting as a **prompt architect**. Your job:
+
+Transform an unstructured task request into a constrained, strategy-driven prompt that prevents over-generation and verbosity.
+
+**You will receive:**
+
+- Task description (what needs to be generated)
+- Content (the actual content to analyze/optimize)
+- Output type (skill / docs / plan / instructions / other)
+- Complexity level (low / medium / high - or infer it)
+- Constraints (max length, format, audience, exclusions - or none)
+- Architecture reference (optional file path to architecture specification)
+- Mode (optional: "consult" or "optimize", defaults to "optimize")
+
+**You will output (mode=optimize):**
+
+- Analysis of complexity and bloat risks
+- 2-3 selected strategies with rationale
+- Optimized, constrained prompt (ready to use)
+- Summary of constraints applied
+
+**You will output (mode=consult):**
+
+- Analysis of complexity and bloat risks
+- Recommended strategies with rationale
+- Optimization potential assessment
+- Recommendations (no optimized prompt)
+
+## Analysis Mode
+
+ULTRATHINK: Prioritize accuracy over speed. Take time to:
+
+- **Semantic before syntactic**: What is this actually trying to accomplish?
+- Identify content type (agent/workflow vs docs/skills)
+- Distinguish bloat from necessary procedural detail
+- **Research-informed structure decisions**: Formatting impacts performance significantly (40%+ variance in template studies); practical experience suggests enumeration helps for 3+ sequential steps
+- Select appropriate reduction target (40-50% vs 60%+)
+- Choose optimal strategy combination (1-3 max)
+
+**Core principle (research-validated)**: Prompt formatting significantly impacts LLM performance (up to 40% variance, sometimes 300%+). Structure provides cognitive anchors that reduce hallucination and improve thoroughness. Default to enumeration for 3+ steps; use natural language only when structure adds no clarity.
+
+**Key research findings**:
+
+- Numbered lists help LLMs understand sequential steps and address each point thoroughly
+- Structure reduces ambiguity about task sequence
+- LLMs mirror the formatting structure you provide
+- Enumeration works not because of the numbers, but because of pattern consistency and correct ordering
+
+Careful analysis prevents over-optimization and vague instructions.
+
+## Process
+
+Follow these steps:
+
+1. Read reference materials (strategies, anti-patterns, examples from references/)
+2. Analyze the task (complexity, bloat risks, structure needs, target length)
+3. Select 1-3 strategies based on complexity score and bloat risks
+4. Generate output (optimized prompt or consultation analysis depending on mode)
+
+### Step 1: Read Reference Materials
+
+ALWAYS start by reading these files (progressive disclosure loads them on-demand):
+
+- `~/.claude/skills/prompt-architecting/references/STRATEGIES.md` (15 prompting strategies catalog)
+- `~/.claude/skills/prompt-architecting/references/ANTI-PATTERNS.md` (basic bloat patterns)
+- `~/.claude/skills/prompt-architecting/references/ADVANCED-ANTI-PATTERNS.md` (workflow/agent patterns - read if optimizing workflows)
+- `~/.claude/skills/prompt-architecting/references/EXAMPLES.md` (basic case studies)
+- `~/.claude/skills/prompt-architecting/references/ADVANCED-EXAMPLES.md` (workflow/agent case studies - read if optimizing workflows)
+
+IF architecture_reference provided:
+
+- Read the architecture file at the provided path
+- Understand required sections, patterns, and structural requirements
+- This will guide refactoring in Step 4
+
+### Step 2: Analyze the Task
+
+Evaluate and explicitly STATE:
+
+**FIRST: Safety checks (prevent harmful optimization)**
+
+Check if content should NOT be optimized:
+
+- Already optimal pattern? (deliverable-first + natural/appropriate structure + right complexity + appropriate notation)
+- Callable entity description at correct structure? (context + triggers present)
+- Agent/workflow at 40-50% of bloated version with specificity intact?
+- Technical notation serving clear purpose? (API specs, standard conventions, precision needed)
+- User requests preservation?
+
+**If any YES**: STATE "Optimization not recommended: [reason]" and use mode=consult to provide analysis only.
+
+- **Semantic analysis** (SECOND - most important):
+
+  - What is the core job this is trying to accomplish?
+  - Can it be expressed as a single coherent task in natural language?
+  - Test: Describe in one sentence using "then/if/when" connectors
+  - Example: "Read file, optimize with skill (preserving header if present), write back"
+  - **If YES**: Consider natural language reframing instead of formal structure
+  - **If NO**: Task may need structured breakdown
+
+- **Complexity scoring** (determines structure level):
+  Calculate score based on these factors:
+
+  - 1-2 steps with obvious sequence? → **-1 point**
+  - 3-4 steps where sequence matters? → **+1 point**
+  - 5+ sequential steps? → **+2 points**
+  - Has user approval gates (WAIT, AskUserQuestion)? → **+3 points**
+  - Has 2+ terminal states (different end conditions)? → **+2 points**
+  - Has 3-way+ conditional branching? → **+2 points**
+  - Simple if/else conditionals only? → **+0 points**
+  - Skill invocation just for data gathering? → **+0 points**
+  - Skill invocation affects control flow decisions? → **+1 point**
+
+  **Score interpretation** (research-aligned):
+
+  - Score ≤ 0: Natural language framing acceptable (1-2 simple steps)
+  - Score 1-2: Numbered enumeration helps (research: improves thoroughness, reduces ambiguity)
+  - Score 3-4: Moderate structure (enumeration + opening mandate, no EXECUTION RULES)
+  - Score ≥ 5: Full formal structure (complete EFC pattern with EXECUTION RULES)
+
+- **Bloat risks**: What specifically could cause over-generation? (edge cases, theoretical coverage, defensive documentation, etc.)
+
+- **Workflow structure assessment**:
+
+  - Count sequential steps in input (look for "Step 1", "Step 2", numbered workflow)
+  - Check for skill/agent invocations (are they just data gathering or control flow?)
+  - Check for user approval gates (AskUserQuestion, explicit WAIT/STOP)
+  - Check for multiple terminal states (different ways the task can end)
+  - Check if input already has Execution Flow Control (opening mandate, data flow notation, EXECUTION RULES)
+  - **Structure determination** based on complexity score:
+    - "Complexity score: [X]. Recommendation: [Natural language / Light structure / Moderate structure / Full EFC]"
+
+- **Target length**: Calculate optimal word/line count based on complexity and output type
+
+- **Architecture compliance** (if architecture_reference provided):
+  - Compare input structure to architecture requirements
+  - Identify missing required sections
+  - Identify structural misalignments
+  - State: "Architecture: [compliant/partial/non-compliant]. Missing: [list]. Misaligned: [list]."
+
+**Dimensional analysis (if optimization appropriate)**
+
+Evaluate each dimension:
+
+**Dimension 1 (Verbosity):**
+
+- Bloat indicators present? (adjective-heavy, scope inflation, vague quality statements, meta-discussion, filler, repetition)
+- Current word count vs. ideal for task? (>2x ideal = bloat)
+- State: "Verbosity: [bloated/concise/appropriate]. Reduction needed: [yes/no]"
+
+**Dimension 2 (Structure):**
+
+- Complexity score already calculated above
+- Current structure level: [none/minimal/moderate/full]
+- Appropriate structure level for score: [natural/light/moderate/full]
+- Structure mismatch? [over-structured/under-structured/appropriate]
+- State: "Complexity score: [X]. Current structure: [level]. Needed: [level]. Mismatch: [yes/no]"
+
+**Dimension 3 (Notation):**
+
+- Technical notation assessment:
+  - CAPS labels as action markers? (CHECK:, PARSE:, etc.)
+  - → notation for data flow? (→ variable_name)
+  - Variable naming conventions? (work_file_status, requirement_data)
+  - Function call syntax? (tool({params}))
+  - Sub-step enumeration? (a/b/c)
+  - Defensive meta-instructions? ("DO NOT narrate")
+- Count indicators (3+ = over-technical)
+- Does notation serve precision purpose? (API specs, schemas, standard conventions)
+- Cognitive load test: Does notation make it easier or harder to understand?
+- State: "Technical notation: [X indicators]. Purpose: [precision/ceremony]. Cognitive load: [helps/hurts/neutral]. Assessment: [over-technical/appropriate]"
+
+**Callable entity check** (if description field):
+
+- Contextual "when" conditions: present/vague/missing
+- Trigger phrases (quoted literals): present/weak/missing
+- Delegation signals if subagent: present/missing/N/A
+- Integration points: present/missing/N/A
+- Structure: complete/context-only/triggers-only/missing
+
+**Workflow pattern detection** (if skill/agent invocations):
+
+- High-risk stopping patterns present? (CAPS + → + variables + remote rules + warnings)
+- Classification: high-risk / optimal / standard
+- Stopping risk: yes/no
+- Note: High-risk patterns are Dimension 3 problem (over-technical notation)
+
+**Complexity guidelines:**
+
+| Level  | Target Length | Notes                                     |
+| ------ | ------------- | ----------------------------------------- |
+| Low    | 100-200w      | Straightforward tasks                     |
+| Medium | 200-400w      | Moderate scope                            |
+| High   | 400-600w      | Use progressive disclosure to references/ |
+
+### Step 3: Select Strategies
+
+**MANDATORY EXCLUSIONS (based on Step 2 safety checks):**
+
+- If already optimal: STOP - recommend no optimization
+- If complexity score ≤ 0: NEVER use EFC, Decomposition, or Template-Based
+- If callable entity: MUST use Callable Entity Preservation, MAX 1 additional strategy
+- If technical notation serves precision purpose: PRESERVE notation, optimize other dimensions only
+
+**MANDATORY SELECTIONS (based on Step 2 dimensional analysis):**
+
+**For Dimension 1 (Verbosity problems):**
+
+- MUST select: Constraint-Based (hard word limits)
+- SHOULD select: Negative Prompting (if specific bloat patterns identified)
+- MAY select: Progressive Disclosure (if complex topic with separable details)
+
+**For Dimension 2 (Structure mismatch):**
+
+- If over-structured (score ≤ 0 but has formal structure):
+  - MUST select: Natural Language Reframing
+- If under-structured (score ≥ 3 but vague prose):
+  - Score 3-4: Moderate structure (organized natural, no heavy formality)
+  - Score ≥ 5: Goal + Capabilities pattern
+  - MAY select: Decomposition, Directive Hierarchy
+
+**For Dimension 3 (Over-technical notation):**
+
+- If over-technical detected (3+ indicators, cognitive load hurts):
+  - MUST select: Technical → Natural Transformation
+  - This often solves stopping risk simultaneously
+  - May be SUFFICIENT optimization (don't over-optimize)
+
+**For Callable Entities (detected in Step 2):**
+
+- MUST select: Callable Entity Preservation
+- Focus on preserving/adding both layers (context + triggers)
+
+**For High-Risk Workflows (detected in Step 2):**
+
+- MUST select: Technical → Natural Transformation (removes stopping risk)
+- Preserve appropriate structure level (based on complexity score)
+- Remove ceremony (CAPS, →, variables, warnings)
+
+**STRATEGY COUNT LIMIT: 1-3 strategies max**
+
+- 1 strategy: Simple reframing or notation simplification
+- 2 strategies: Most common (address 2 dimensions or primary + constraint)
+- 3 strategies: Complex only (rarely needed)
+
+**NEVER exceed 3 strategies** (over-optimization risk)
+
+**COMPLEMENTARY CHECK:**
+
+- Verify selected strategies don't conflict (see compatibility matrix in STRATEGIES.md)
+- If conflict detected, choose most important strategy and drop conflicting ones
+
+### Step 4: Generate Output
+
+Based on mode:
+
+**IF mode=consult:**
+
+- DO NOT generate optimized prompt
+- Output analysis, recommended strategies, and optimization potential
+- If architecture provided, include architecture compliance assessment
+- Use consult output format (see Output Format section below)
+
+**IF mode=optimize (default):**
+
+**Primary principle**: Reduce cognitive load while preserving intent.
+
+**Apply selected strategies based on dimensions:**
+
+**For Dimension 1 (Verbosity):**
+
+- Remove adjectives and quality statements
+- Set hard word/line limits
+- Use template structure to bound scope
+- Exclude known bloat patterns explicitly
+- Target: 60%+ reduction for docs OK, 40-50% for agents/workflows
+
+**For Dimension 2 (Structure):**
+
+Match structure to complexity score:
+
+- **Score ≤ 0 (Natural language)**:
+
+  - Rewrite as clear prose with connectors ("then", "if", "when")
+  - Avoid enumeration unless truly necessary
+  - Embed conditionals inline naturally
+  - Example: "Read the file, optimize content, and write back"
+
+- **Score 1-2 (Light structure)**:
+
+  - Simple numbered steps or sections without heavy formality
+  - Natural language throughout
+  - No CAPS labels, no → notation
+  - Example: "1. Read file 2. Optimize 3. Write result"
+
+- **Score 3-4 (Organized natural with structure)**:
+
+  - Logical sections or phases (Setup, Analysis, Execution, etc.)
+  - Natural language within structured organization
+  - NO CAPS/→/variables
+  - Completion criterion inline or immediately after
+  - Example: See "appropriately optimized" examples in OPTIMIZATION-SAFETY-GUIDE.md
+
+- **Score ≥ 5 (Goal + Capabilities + organized workflow)**:
+  - Goal statement (ultimate outcome upfront)
+  - Capabilities declaration (tools/skills needed)
+  - Organized workflow with natural language
+  - Clear terminal conditions
+  - STILL use natural notation (no CAPS/→/variables)
+
+**For Dimension 3 (Over-technical notation):**
+
+Remove ceremonial technical notation:
+
+- CAPS labels → natural section headers or action verbs
+- → notation → implicit data flow or prose
+- Variable names → eliminate or minimize
+- Function call syntax → natural tool mentions
+- Sub-step enumeration → consolidate to prose
+- Defensive warnings → remove entirely (trust structure)
+- Remote EXECUTION RULES → integrate inline or remove
+
+While preserving:
+
+- Appropriate structure level (based on complexity score)
+- All requirements and dependencies
+- Tool invocations (mentioned naturally)
+- Terminal conditions (integrated naturally)
+
+**For Callable Entities:**
+
+- Preserve both contextual "when" AND trigger phrases
+- Add missing layer if incomplete
+- Minimal optimization (10-20% max)
+- Focus on invocation clarity
+
+**General optimization:**
+
+- Sets hard word/line limits (Constraint-Based)
+- Specifies structure (Template-Based or Output Formatting if applicable)
+- Excludes known bloat patterns (Negative Prompting if applicable)
+- Embeds selected strategies naturally into instructions
+
+**If architecture_reference provided:**
+
+- Refactor content to align with architecture requirements
+- Add missing required sections (Purpose, Workflow, Output, etc.)
+- Preserve required patterns (asset references, error formats, etc.)
+- Optimize content WITHIN architectural structure (don't remove structure)
+
+**FINAL SAFETY CHECK before returning:**
+
+Verify optimized version:
+
+- [ ] Clarity test: Is it clearer than original? (cognitive load lower)
+- [ ] Intent test: Core requirements preserved?
+- [ ] Complexity match: Structure appropriate for score?
+- [ ] Notation appropriate: Natural unless technical serves precision purpose?
+- [ ] No new problems: No stopping points, lost triggers, introduced ambiguity?
+- [ ] Executable: Would LLM follow this successfully?
+- [ ] Reduction appropriate: 40-50% agents/workflows, 60%+ docs
+- [ ] Strategy count: 1-3, complementary
+
+**If any check FAILS**: Revise optimization or recommend consult mode only.
+
+## Output Format
+
+You MUST structure your response based on mode:
+
+**For mode=optimize:**
+
+```markdown
+## Analysis
+
+- Task complexity: {low|medium|high}
+- Primary bloat risks: {2-3 specific risks identified}
+- Architecture compliance: {if architecture_reference provided}
+- Target length: {calculated word/line count based on complexity}
+
+## Selected Strategies
+
+- **{Strategy Name}**: {1 sentence why chosen for this specific task}
+- **{Strategy Name}**: {1 sentence why chosen}
+- **{Strategy Name}** (if needed): {1 sentence why chosen}
+
+## Optimized Prompt
+
+{The actual constrained prompt - this gets used directly by the executor}
+
+{Prompt should be 3-10 sentences with:
+
+- Clear scope boundaries
+- Specific word/line limits
+- Explicit structure (sections, format)
+- DO NOT clauses if bloat risks identified
+- Reference to examples if anchoring strategy used
+- Architecture alignment directives (if architecture provided)}
+
+## Constraints Applied
+
+- Word/line limits: {specific counts}
+- Structure: {template or format specified}
+- Exclusions: {what NOT to include}
+- Architecture: {required sections/patterns preserved if applicable}
+- Other: {any additional constraints}
+```
+
+**For mode=consult:**
+
+```markdown
+## Analysis
+
+- Task complexity: {low|medium|high}
+- Primary bloat risks: {2-3 specific risks identified}
+- Architecture compliance: {if architecture_reference provided}
+- Target length: {calculated word/line count based on complexity}
+
+## Recommended Strategies
+
+- **{Strategy Name}**: {1 sentence why recommended for this specific task}
+- **{Strategy Name}**: {1 sentence why recommended}
+- **{Strategy Name}** (if needed): {1 sentence why recommended}
+
+## Optimization Potential
+
+- Content reduction: {estimated percentage - e.g., "40-50% reduction possible"}
+- Structural changes needed: {list if architecture provided - e.g., "Add Output Format section, refactor steps"}
+- Bloat removal: {specific areas - e.g., "Remove verbose library comparisons, consolidate examples"}
+
+## Recommendations
+
+{2-4 sentence summary of what should be done to optimize this content}
+```
+
+## Errors
+
+**"Missing required parameter"**: Task description or content not provided. Cannot analyze without content to optimize. Provide: task description, content, output type.
+
+**"Invalid architecture_reference path"**: File path doesn't exist or isn't readable. Verify path exists: ~/.claude/skills/skill-generator/references/SKILL-ARCHITECTURE.md
+
+**"Unsupported output type"**: Output type not recognized. Supported: skill, docs, plan, instructions, command, agent.
+
+**"Mode parameter invalid"**: Mode must be "optimize" or "consult". Defaults to "optimize" if not specified.