| name | plan-moat-strategy |
| author | JM Labs (Javier Montaño) |
| description | Design MOAT asset strategy per skill: which subdirectories needed, what content they contain, naming conventions. Trigger: plan MOAT, MOAT strategy, asset planning, reference planning, plan skill assets.
|
| argument-hint | <architecture-plan-path> |
| allowed-tools | ["Read","Write","Glob","Grep","Bash"] |
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.
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).
- Skills that produce artifacts the user must understand: always include examples/ (minimum FULL).
- Skills that elicit user input through structured questions: always include prompts/ (DEEP).
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).
- Reference files:
{topic}-{type}.md where type is one of: spec, guide, matrix, patterns, framework.
- Example files:
sample-{artifact}.md.
- Prompt files:
{purpose}-prompts.md.
- 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
Quality Criteria
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.
Missing: no per-skill justification, no complexity assessment, no naming conventions, no line estimates.
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.
Includes: per-skill complexity scores, depth with rationale, specific asset files with line estimates, justification.
Anti-Patterns
- Giving every skill DEEP MOAT depth regardless of complexity (wasteful, dilutes quality).
- Creating references/ with only links and no substantive content.
- Using examples/ for test cases instead of illustrative samples.
- Estimating line counts without considering the actual content needed.
- Naming files generically (
notes.md, info.md) instead of descriptively.
Edge Cases
- A skill's complexity changes during design -- revisit the MOAT allocation.
- Multiple skills share the same reference material -- create one reference file and cross-link.
- A MINIMAL skill grows in scope -- upgrade its MOAT depth and document why.
