Plan MOAT Strategy

"A skill without references is a skill that hallucinates. A skill without examples is a skill that guesses."

Design the MOAT (Materials, Ontology, Assets, Templates) asset allocation for each skill in a plugin. Determines which subdirectories each skill needs, what content they should contain, naming conventions, and estimated line counts. [EXPLICIT]

---

Procedure

Step 1 -- Read Architecture Plan

• Read the architecture plan document at the provided path.
• Extract the skill-movement map with all skill names and purposes.
• If no architecture plan exists, report error and suggest running /pqa:plan first.
• Tag source: [DOC].

Step 2 -- Assess Complexity Per Skill

• For each skill, evaluate complexity across four dimensions:

Dimension	Low (1)	Medium (2)	High (3)
Domain knowledge	Common knowledge	Requires reference docs	Deep specialist knowledge
Procedure steps	3-4 steps	5-7 steps	8+ steps
Edge cases	1-2 obvious	3-4 nuanced	5+ with subtle interactions
User interaction	No user prompting	Some clarification needed	Extensive elicitation

• Sum the scores: 4-5 = LOW, 6-8 = MEDIUM, 9-10 = HIGH, 11-12 = VERY HIGH.
• Record the score and justification for each skill. [INFERENCIA]

Step 3 -- Determine MOAT Depth

• Map complexity scores to MOAT depth:

Complexity	MOAT Depth	Subdirectories
LOW (4-5)	MINIMAL	SKILL.md only
MEDIUM (6-8)	STANDARD	SKILL.md + references/
HIGH (9-10)	FULL	SKILL.md + references/ + examples/
VERY HIGH (11-12)	DEEP	SKILL.md + references/ + examples/ + prompts/

• Override rules:
  • Skills that reference external specs or standards: always include references/ (minimum STANDARD). [EXPLICIT]
  • Skills that produce artifacts the user must understand: always include examples/ (minimum FULL). [EXPLICIT]
  • Skills that elicit user input through structured questions: always include prompts/ (DEEP). [EXPLICIT]

Step 4 -- Plan Content for Each Subdirectory

For each skill at STANDARD or above, specify:

references/ -- What reference documents to create:

• Name: {topic}-{type}.md (e.g., hook-compatibility-matrix.md, frontmatter-spec.md).
• Purpose: One sentence describing what knowledge it captures.
• Estimated lines: 30-100 depending on complexity.

examples/ -- What example documents to create:

• Name: sample-{artifact}.md (e.g., sample-architecture-plan.md).
• Purpose: One sentence describing the example scenario.
• Estimated lines: 30-80.

prompts/ -- What prompt templates to create:

• Name: {purpose}-prompts.md (e.g., ideation-prompts.md).
• Purpose: One sentence describing the question set.
• Estimated lines: 20-50.

Step 5 -- Define Naming Conventions

• Document the naming conventions for the plugin:
  • Skill directories: kebab-case verb-noun (e.g., validate-hooks). [EXPLICIT]
  • Reference files: {topic}-{type}.md where type is one of: spec, guide, matrix, patterns, framework. [EXPLICIT]
  • Example files: sample-{artifact}.md. [EXPLICIT]
  • Prompt files: {purpose}-prompts.md. [EXPLICIT]
• Verify all proposed names follow the conventions. [CODIGO]

Step 6 -- Estimate Total Asset Count

• Sum all MOAT assets across all skills.
• Produce a summary table:

| Skill | Depth | References | Examples | Prompts | Total Assets |

• Calculate total files to create (SKILL.md files + all MOAT assets).
• Estimate total lines across all assets. [DOC]

Step 7 -- Write MOAT Strategy Document

• Compile into moat-strategy.md:

  # MOAT Strategy: {plugin-name}
  ## Complexity Assessment
  ## Depth Allocation
  ## Asset Inventory
  ## Naming Conventions
  ## Summary
  

• Present for review. Write file only on user confirmation.
• Reference references/moat-quality-dimensions.md for scoring details.

---

Quality Criteria

• Every skill has an explicit MOAT depth with documented justification. [DOC]
• Naming conventions are consistent across all proposed assets. [CODIGO]
• Override rules are applied correctly (spec-referencing skills have references/). [DOC]
• Line count estimates are realistic (not padding, not underestimating). [INFERENCIA]
• Total asset count is proportional to plugin complexity. [DOC]

Assumptions & Limits

• This skill produces a strategy document, not files. The actual MOAT directories and content are created by build-moat-assets.
• Complexity assessment is heuristic-based (4-dimension scoring). Two skills with the same score may have very different MOAT needs.
• Line count estimates assume standard markdown density (~30 words per line). Highly structured content (tables, code blocks) may need more lines for the same information.
• Override rules are PQA conventions, not official spec requirements. Plugins outside the PQA ecosystem may use different MOAT depth criteria.
• Shared references (Edge Case 2) are recommended but the skill cannot enforce cross-linking -- that is validated by validate-cross-refs.

Good vs Bad

Bad MOAT strategy:

All skills: DEEP.
References: yes. Examples: yes. Prompts: yes. [EXPLICIT]

Missing: no per-skill justification, no complexity assessment, no naming conventions, no line estimates. [EXPLICIT]

Good MOAT strategy:

| Skill | Complexity | Depth | References | Examples | Prompts |
|-------|-----------|-------|------------|----------|---------|
| validate-hooks | HIGH (10) | FULL | hook-compatibility-matrix.md (80 lines) | valid-hooks.md, incompatible-hooks.md (40 lines each) | -- |
| ideate-plugin | MEDIUM (7) | STANDARD | plugin-idea-framework.md (60 lines) | -- | -- |

Justification: validate-hooks scores HIGH because it requires deep domain knowledge (hook spec) and has 5+ edge cases. ideate-plugin is MEDIUM — straightforward procedure but needs reference material for overlap analysis. [EXPLICIT]

Includes: per-skill complexity scores, depth with rationale, specific asset files with line estimates, justification. [EXPLICIT]

Anti-Patterns

1. Giving every skill DEEP MOAT depth regardless of complexity (wasteful, dilutes quality). [EXPLICIT]
2. Creating references/ with only links and no substantive content. [EXPLICIT]
3. Using examples/ for test cases instead of illustrative samples. [EXPLICIT]
4. Estimating line counts without considering the actual content needed. [EXPLICIT]
5. Naming files generically (notes.md, info.md) instead of descriptively. [EXPLICIT]

Edge Cases

1. A skill's complexity changes during design -- revisit the MOAT allocation. [EXPLICIT]
2. Multiple skills share the same reference material -- create one reference file and cross-link. [EXPLICIT]
3. A MINIMAL skill grows in scope -- upgrade its MOAT depth and document why. [EXPLICIT]

Usage

Example invocations:

• "/plan-moat-strategy" — Run the full plan moat strategy workflow
• "plan moat strategy on this project" — Apply to current context