prompt-plus-plus-mcp/metaprompts/vibe_coding_rules/document_intent.json

Advanced MCP server with 44+ metaprompt strategies including AI Core Principles, Vibe Coding Rules, and metadata-driven intelligent selection

{
  "name": "Document Intent, Not Implementation",
  "description": "Focus documentation on why decisions were made and what problems are being solved, not how the code works. Code should be self-documenting for the 'how'.",
  "template": "You are an AI assistant implementing the 'Document Intent, Not Implementation' principle from the Vibe Coding Rules. Your task is to create meaningful documentation that captures decision rationale, business context, and design choices.\n\nFollow this intent-focused documentation framework:\n\n1. **Documentation Levels**:\n   - **Architecture Decisions**: Why this design\n   - **Business Logic**: Why these rules\n   - **API Design**: Why these contracts\n   - **Algorithm Choice**: Why this approach\n   - **Trade-offs**: Why these compromises\n   - **Future Considerations**: Why plan for X\n\n2. **Intent Documentation Types**:\n   - **ADRs**: Architecture Decision Records\n   - **Code Comments**: Why, not what\n   - **README**: Problem and solution\n   - **API Docs**: Use cases and constraints\n   - **Commit Messages**: Change rationale\n   - **PR Descriptions**: Context and impact\n\n3. **Self-Documenting Code**:\n   - Clear naming conventions\n   - Small, focused functions\n   - Expressive variable names\n   - Type definitions\n   - Consistent patterns\n   - Obvious structure\n\n4. **When to Document**:\n   - Non-obvious decisions\n   - Business rule encoding\n   - Performance optimizations\n   - Security considerations\n   - Workarounds and hacks\n   - Future refactoring notes\n\n5. **Documentation Quality**:\n   - Answers \"why\" questions\n   - Provides context\n   - Explains constraints\n   - Records alternatives\n   - Captures assumptions\n   - Links to resources\n\n6. **Maintenance Strategy**:\n   - Living documentation\n   - Review triggers\n   - Deprecation process\n   - Version control\n   - Search optimization\n   - Team accessibility\n\nInitial prompt: [Insert initial prompt here]\n\nPlease provide your response in the following JSON format:\n\n<json>\n{\n  \"initial_prompt\": \"The original prompt provided\",\n  \"documentation_audit\": {\n    \"current_state\": {\n      \"documentation_coverage\": \"High/Medium/Low\",\n      \"quality_assessment\": \"Good/Fair/Poor\",\n      \"common_issues\": [\n        \"Explains how not why\",\n        \"Outdated information\",\n        \"Missing context\"\n      ],\n      \"strengths\": [\"What works well\"]\n    },\n    \"improvement_areas\": [\n      {\n        \"area\": \"Code comments\",\n        \"current_approach\": \"Line-by-line how\",\n        \"better_approach\": \"Block-level why\",\n        \"priority\": \"High/Medium/Low\"\n      }\n    ]\n  },\n  \"intent_documentation_plan\": [\n    {\n      \"artifact_type\": \"ADR/README/Comment/API Doc\",\n      \"subject\": \"What to document\",\n      \"key_decisions\": [\n        {\n          \"decision\": \"Specific choice made\",\n          \"rationale\": \"Why this way\",\n          \"alternatives_considered\": [\"Option A\", \"Option B\"],\n          \"trade_offs\": \"What we gave up\",\n          \"constraints\": \"What limited us\"\n        }\n      ],\n      \"audience\": \"Future developers/Users/Ops\",\n      \"maintenance_plan\": \"When to update\"\n    }\n  ],\n  \"code_refactoring_for_clarity\": [\n    {\n      \"current_code\": \"Unclear implementation\",\n      \"refactored_version\": \"Self-documenting code\",\n      \"improvements\": [\n        \"Better naming\",\n        \"Extracted methods\",\n        \"Type clarity\"\n      ],\n      \"documentation_removed\": \"No longer needed comments\"\n    }\n  ],\n  \"documentation_templates\": [\n    {\n      \"template_type\": \"ADR\",\n      \"structure\": {\n        \"title\": \"Decision title format\",\n        \"status\": \"Proposed/Accepted/Deprecated\",\n        \"context\": \"What led to this decision\",\n        \"decision\": \"What we're doing\",\n        \"consequences\": \"What happens as a result\",\n        \"alternatives\": \"What else we considered\"\n      },\n      \"example\": \"Filled template example\"\n    },\n    {\n      \"template_type\": \"Intent Comment\",\n      \"format\": \"// Why: [business reason]\\n// Constraint: [limitation]\\n// Future: [consideration]\",\n      \"when_to_use\": \"Non-obvious logic\"\n    }\n  ],\n  \"anti_patterns_to_fix\": [\n    {\n      \"anti_pattern\": \"Redundant how comments\",\n      \"example\": \"// Increment counter\\ncounter++\",\n      \"fix\": \"Remove or explain why incrementing\",\n      \"detection\": \"Comments that mirror code\"\n    },\n    {\n      \"anti_pattern\": \"Missing context\",\n      \"example\": \"Magic numbers without explanation\",\n      \"fix\": \"Document business rule source\",\n      \"impact\": \"Future confusion\"\n    }\n  ],\n  \"living_documentation\": {\n    \"update_triggers\": [\n      \"Major feature addition\",\n      \"Architecture change\",\n      \"Performance optimization\",\n      \"Security update\"\n    ],\n    \"review_schedule\": {\n      \"frequency\": \"Quarterly/Bi-annual\",\n      \"participants\": \"Tech lead + team\",\n      \"focus_areas\": [\"Accuracy\", \"Relevance\", \"Completeness\"]\n    },\n    \"deprecation_process\": [\n      \"Mark as deprecated\",\n      \"Add migration guide\",\n      \"Set removal date\",\n      \"Archive after removal\"\n    ]\n  },\n  \"team_guidelines\": [\n    {\n      \"guideline\": \"Document why, not how\",\n      \"examples\": {\n        \"good\": \"// Using cache to handle 10K requests/sec requirement\",\n        \"bad\": \"// This function adds item to cache\"\n      },\n      \"enforcement\": \"PR review checklist\"\n    },\n    {\n      \"guideline\": \"Keep docs near code\",\n      \"rationale\": \"Higher chance of updates\",\n      \"implementation\": \"Same repo, close proximity\"\n    }\n  ],\n  \"measurement_strategy\": {\n    \"documentation_quality\": [\n      {\n        \"metric\": \"Why vs How ratio\",\n        \"measurement\": \"Comment analysis\",\n        \"target\": \"80% why-focused\"\n      },\n      {\n        \"metric\": \"Decision coverage\",\n        \"measurement\": \"ADRs per major feature\",\n        \"target\": \"All significant decisions\"\n      }\n    ],\n    \"team_understanding\": {\n      \"assessment\": \"Onboarding time\",\n      \"baseline\": \"Current duration\",\n      \"improvement_goal\": \"50% reduction\"\n    }\n  },\n  \"key_insights\": [\n    \"Critical decisions lacking documentation\",\n    \"Code clarity improvements reduce doc needs\",\n    \"Team alignment on documentation standards\"\n  ],\n  \"recommendation\": \"Specific documentation improvement plan with priorities\"\n}\n</json>",
  "examples": [
    "Document architectural decisions for microservices",
    "Improve API documentation with use cases",
    "Replace how-comments with why-comments",
    "Create ADRs for technology choices"
  ]
}