incitaciones 0.3.0 → 0.3.2

package/content/distilled/review-documentation/references/ai-readiness-criteria.md

@@ -0,0 +1,38 @@
+# AI-Readiness Criteria (Pass 5)
+
+Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer First) catches surface issues; these checks catch whether the page is actually consumable by an AI agent. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability").
+
+## LLM-friendly structure
+
+- Is there a concise TL;DR (1-2 sentences) at the top suitable for context-window injection?
+- Is the page free of navigation chrome when exported (menus, footers, ads) so the body text is clean?
+- Is prose minimalist and high-signal? Verbose docs cost more and retrieve worse.
+
+## RAG-compatible chunking
+
+- Does the page cover one well-defined topic so it chunks cleanly for retrieval?
+- Are section headings stable and unique so a chunk can be addressed precisely?
+- Is there redundant cross-page duplication that would pollute retrieval results?
+
+## Semantic headers
+
+- Are headers descriptive of content, not generic ("Overview", "Details")?
+- Are headers unique across the site so a model can disambiguate?
+- Is front matter present (title, description, version, category) for indexing?
+
+## Dual-audience precision
+
+- Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
+- Are error conditions and their meanings explicit?
+- Are capability boundaries stated (what the tool/API can and cannot do)?
+
+## Schema and spec sync (reference pages)
+
+- For API reference: is it generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
+- For tool/agent docs: are MCP manifests and agent cards present with precise descriptions and JSON schemas for inputs/outputs?
+- Are code examples complete and runnable? Agents execute what they read; partial snippets mislead.
+
+## Site-level (flag only if the page is the canonical entry)
+
+- Is a `llms.txt` present at the documentation root and does it reference this page where authoritative?
+- Are canonical URLs set so a model retrieves the current stable version?

package/content/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-07-27",
+  "version": "2026-07-29",
   "schema_version": "1.1",
   "prompts": [
     {
@@ -2223,17 +2223,137 @@
       "title": "Research and Audit Documentation Architecture",
       "description": "Audit existing documentation or plan a new suite using advanced frameworks",
       "source": "content/prompt-task-research-documentation.md",
-      "distilled": "content/distilled/research-documentation.md",
+      "distilled": "content/distilled/research-documentation/SKILL.md",
+      "skill_format": "progressive-disclosure",
       "tags": [
         "research",
         "documentation",
         "audit",
-        "information-architecture"
+        "information-architecture",
+        "diataxis",
+        "eppo",
+        "llm-readiness"
       ],
       "bundles": [
         "documentation",
         "research"
-      ]
+      ],
+      "eval": {
+        "task_types": [
+          "research",
+          "documentation",
+          "audit"
+        ],
+        "success_signals": [
+          "core_assertion_stated",
+          "every_doc_classified_to_one_quadrant",
+          "frankenbooks_flagged",
+          "eppo_compliance_checked",
+          "ai_readiness_assessed",
+          "measurement_signals_recommended",
+          "report_produced"
+        ],
+        "failure_signals": [
+          "content_drafted",
+          "stylistic_changes_suggested",
+          "quadrant_overlap_unflagged",
+          "missing_report"
+        ],
+        "stages": [
+          {
+            "name": "define-scope",
+            "hints": [
+              "primary audience",
+              "core assertion",
+              "value proposition"
+            ]
+          },
+          {
+            "name": "audit-content",
+            "hints": [
+              "references/checklist.md",
+              "diataxis quadrant",
+              "eppo status",
+              "cognitive load"
+            ]
+          },
+          {
+            "name": "map-snowflake",
+            "hints": [
+              "macro-expansion",
+              "component list",
+              "topic matrix"
+            ]
+          },
+          {
+            "name": "identify-gaps",
+            "hints": [
+              "references/llm-readiness.md",
+              "references/metrics.md",
+              "quadrant imbalance",
+              "llms.txt",
+              "rag chunking"
+            ]
+          },
+          {
+            "name": "produce-report",
+            "hints": [
+              "references/report-template.md",
+              "final report"
+            ]
+          }
+        ],
+        "references": [
+          {
+            "id": "checklist",
+            "path": "content/distilled/research-documentation/references/checklist.md",
+            "purpose": "audit-checklist",
+            "stage": "audit-content",
+            "optional": false,
+            "aliases": [
+              "references/checklist.md",
+              "checklist.md",
+              "checklist"
+            ]
+          },
+          {
+            "id": "llm-readiness",
+            "path": "content/distilled/research-documentation/references/llm-readiness.md",
+            "purpose": "gap-assessment",
+            "stage": "identify-gaps",
+            "optional": false,
+            "aliases": [
+              "references/llm-readiness.md",
+              "llm-readiness.md",
+              "llm readiness"
+            ]
+          },
+          {
+            "id": "metrics",
+            "path": "content/distilled/research-documentation/references/metrics.md",
+            "purpose": "measurement-signals",
+            "stage": "identify-gaps",
+            "optional": false,
+            "aliases": [
+              "references/metrics.md",
+              "metrics.md",
+              "metrics"
+            ]
+          },
+          {
+            "id": "report-template",
+            "path": "content/distilled/research-documentation/references/report-template.md",
+            "purpose": "output-template",
+            "stage": "produce-report",
+            "optional": false,
+            "aliases": [
+              "references/report-template.md",
+              "report-template.md",
+              "report template"
+            ]
+          }
+        ]
+      }
     },
     {
       "name": "implement-documentation",
@@ -2241,15 +2361,152 @@
       "title": "Implement High-Signal Documentation Topics",
       "description": "Write documentation using Diátaxis, Info Mapping, and EPPO principles",
       "source": "content/prompt-task-implement-documentation.md",
-      "distilled": "content/distilled/implement-documentation.md",
+      "distilled": "content/distilled/implement-documentation/SKILL.md",
+      "skill_format": "progressive-disclosure",
       "tags": [
         "implementation",
         "documentation",
-        "technical-writing"
+        "technical-writing",
+        "diataxis",
+        "info-mapping",
+        "eppo",
+        "versioning"
       ],
       "bundles": [
         "documentation"
-      ]
+      ],
+      "eval": {
+        "task_types": [
+          "implementation",
+          "documentation",
+          "writing"
+        ],
+        "success_signals": [
+          "quadrant_identified",
+          "matching_template_used",
+          "context_block_present",
+          "content_chunked_and_labeled",
+          "tldr_present",
+          "anti_patterns_avoided"
+        ],
+        "failure_signals": [
+          "mixed_intent",
+          "missing_context_block",
+          "generic_headers",
+          "missing_tldr",
+          "faq_antipattern_used"
+        ],
+        "stages": [
+          {
+            "name": "quadrant-check",
+            "hints": [
+              "references/templates.md",
+              "references/anti-patterns.md",
+              "tutorial",
+              "how-to",
+              "reference",
+              "explanation"
+            ]
+          },
+          {
+            "name": "eppo-init",
+            "hints": [
+              "title",
+              "context block",
+              "prerequisites"
+            ]
+          },
+          {
+            "name": "info-mapping",
+            "hints": [
+              "chunking",
+              "labeling",
+              "tables",
+              "lists"
+            ]
+          },
+          {
+            "name": "ai-polish",
+            "hints": [
+              "semantic headers",
+              "tldr",
+              "rag indexing"
+            ]
+          },
+          {
+            "name": "setup-tooling",
+            "hints": [
+              "references/tooling-comparison.md",
+              "references/versioning.md",
+              "references/diataxis-implementation.md",
+              "platform selection",
+              "versioning strategy"
+            ]
+          }
+        ],
+        "references": [
+          {
+            "id": "templates",
+            "path": "content/distilled/implement-documentation/references/templates.md",
+            "purpose": "output-template",
+            "stage": "quadrant-check",
+            "optional": false,
+            "aliases": [
+              "references/templates.md",
+              "templates.md",
+              "templates"
+            ]
+          },
+          {
+            "id": "anti-patterns",
+            "path": "content/distilled/implement-documentation/references/anti-patterns.md",
+            "purpose": "pitfall-catalog",
+            "stage": "quadrant-check",
+            "optional": false,
+            "aliases": [
+              "references/anti-patterns.md",
+              "anti-patterns.md",
+              "anti patterns"
+            ]
+          },
+          {
+            "id": "tooling-comparison",
+            "path": "content/distilled/implement-documentation/references/tooling-comparison.md",
+            "purpose": "platform-selection",
+            "stage": "setup-tooling",
+            "optional": true,
+            "aliases": [
+              "references/tooling-comparison.md",
+              "tooling-comparison.md",
+              "tooling comparison"
+            ]
+          },
+          {
+            "id": "versioning",
+            "path": "content/distilled/implement-documentation/references/versioning.md",
+            "purpose": "versioning-strategy",
+            "stage": "setup-tooling",
+            "optional": true,
+            "aliases": [
+              "references/versioning.md",
+              "versioning.md",
+              "versioning"
+            ]
+          },
+          {
+            "id": "diataxis-implementation",
+            "path": "content/distilled/implement-documentation/references/diataxis-implementation.md",
+            "purpose": "rollout-guide",
+            "stage": "setup-tooling",
+            "optional": true,
+            "aliases": [
+              "references/diataxis-implementation.md",
+              "diataxis-implementation.md",
+              "diataxis implementation"
+            ]
+          }
+        ]
+      }
     },
     {
       "name": "review-documentation",
@@ -2257,17 +2514,109 @@
       "title": "Review Documentation Quality (Rule of 5)",
       "description": "Iterative review of documentation for cognitive scannability and AI-readiness",
       "source": "content/prompt-task-review-documentation.md",
-      "distilled": "content/distilled/review-documentation.md",
+      "distilled": "content/distilled/review-documentation/SKILL.md",
+      "skill_format": "progressive-disclosure",
       "tags": [
         "review",
         "documentation",
         "technical-writing",
-        "parallel-review"
+        "parallel-review",
+        "diataxis",
+        "eppo",
+        "info-mapping",
+        "ai-readiness"
       ],
       "bundles": [
         "documentation",
         "reviews"
-      ]
+      ],
+      "eval": {
+        "task_types": [
+          "review",
+          "documentation",
+          "quality-assurance"
+        ],
+        "success_signals": [
+          "five_passes_completed_or_converged",
+          "issues_cited_with_locations",
+          "ai_readiness_deep_checked",
+          "final_verdict_present"
+        ],
+        "failure_signals": [
+          "stage_skipping_without_convergence",
+          "vague_findings_without_locations",
+          "shallow_ai_pass_only",
+          "missing_verdict"
+        ],
+        "stages": [
+          {
+            "name": "pass-1-intent",
+            "hints": [
+              "pass 1",
+              "diataxis intent",
+              "leaked intents"
+            ]
+          },
+          {
+            "name": "pass-2-eppo",
+            "hints": [
+              "pass 2",
+              "standalone utility",
+              "context"
+            ]
+          },
+          {
+            "name": "pass-3-scan",
+            "hints": [
+              "pass 3",
+              "scannability",
+              "labels",
+              "chunking"
+            ]
+          },
+          {
+            "name": "pass-4-accuracy",
+            "hints": [
+              "pass 4",
+              "whole game",
+              "fail-states",
+              "martini glass"
+            ]
+          },
+          {
+            "name": "pass-5-ai-readiness",
+            "hints": [
+              "pass 5",
+              "references/ai-readiness-criteria.md",
+              "llms.txt",
+              "rag chunking",
+              "dual-audience"
+            ]
+          },
+          {
+            "name": "final-report",
+            "hints": [
+              "severity totals",
+              "top findings",
+              "verdict"
+            ]
+          }
+        ],
+        "references": [
+          {
+            "id": "ai-readiness-criteria",
+            "path": "content/distilled/review-documentation/references/ai-readiness-criteria.md",
+            "purpose": "deep-ai-readiness-checks",
+            "stage": "pass-5-ai-readiness",
+            "optional": false,
+            "aliases": [
+              "references/ai-readiness-criteria.md",
+              "ai-readiness-criteria.md",
+              "ai readiness criteria"
+            ]
+          }
+        ]
+      }
     },
     {
       "name": "red-team-review",
@@ -3315,4 +3664,4 @@
       ]
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incitaciones",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Reusable prompts and skills for CLI LLM tools, with native pi package support.",
   "repository": {
     "type": "git",

package/pi-package/skills/close/SKILL.md

@@ -14,18 +14,19 @@ tools: Read, Write, Edit, Glob, Bash
 
 End the current session: log what was done, update tasks, route durable knowledge to `~/.whisper/`, commit and push, clear context.
 
-Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log, and `~/.whisper/` for accumulated operational knowledge.
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. The log subdirectory defaults to `log/`; set `$JOURNAL_LOG_SUBDIR` to override (e.g. `areas/log` for the JORNAL layout).
 
 ## Steps
 
 1. Pull the journal repo:
    ```bash
    JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
    cd "$JOURNAL" && git pull
    ```
 
 2. Get today's date and time (`date +%Y-%m-%d`, `date +%H:%M`).
-   Derive the log path: `$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`
+   Derive the log path: `$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`
 
 3. If the log file does not exist, create it with the daily log template.
 

package/pi-package/skills/implement-documentation/SKILL.md

@@ -8,67 +8,28 @@ metadata:
 
 Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
 
-## CRITICAL RULES
+## Core Rules
 
-1. ✅ **DO:** Establish context and prerequisites in the first two sentences (EPPO).
-2. ✅ **DO:** Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
-3. ✅ **DO:** Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
-4. ✅ **DO:** Provide a clear "fail-state" or troubleshooting section (Minimalism).
-5. ❌ **DO NOT:** Mix intents (e.g., no deep theory in a How-to guide). If theory is *required* for a task, use a **Note:** or **Deep Dive:** sidebar to maintain quadrant purity.
-6. ❌ **DO NOT:** Use "Next" or "Previous" as the only navigational cues (EPPO).
+- Establish context and prerequisites in the first two sentences (EPPO).
+- Lead with the answer or primary assertion in the TL;DR and first paragraph (Pyramid Principle).
+- Use explicit, semantic block labels (descriptive headers) for every 2-3 paragraphs (Info Mapping).
+- Provide a clear "fail-state" or troubleshooting section (Minimalism).
+- Do not mix intents: no deep theory in a How-to. If theory is required, use a Note or Deep Dive sidebar to maintain quadrant purity.
+- Do not use "Next" or "Previous" as the only navigational cues (EPPO).
 
-## Implementation Workflow
+## Procedure
 
-### Step 1: Quadrant Check
+1. Quadrant check: identify the Diátaxis quadrant and follow its rhetorical rules. Use `references/templates.md` for the matching template (Tutorial, How-to, Reference, or Explanation). Use `references/anti-patterns.md` to avoid common failures for that quadrant.
+2. EPPO initialization: every topic must stand alone. Start with a clear task- or concept-focused title and a context block ("This topic covers [X]. You should already understand [Y] and have [Z] installed.").
+3. Information mapping: chunk the body into units under 7 items; label headers by result or content (e.g., "Configuring the API" not "Configuration"); convert complex comparisons or steps into tables and lists.
+4. AI-first polish: ensure headers are descriptive for RAG indexing and provide a 1-2 sentence TL;DR at the top for LLM ingestion.
+5. If setting up a new docs site or choosing tooling, use `references/tooling-comparison.md` for platform selection and `references/versioning.md` for versioning and changelog strategy. For a full Diátaxis rollout, use `references/diataxis-implementation.md`.
 
-Identify the Diátaxis quadrant and follow its rhetorical rules:
-- **Tutorial:** Action-oriented, safe environment. Use the **Martini Glass** narrative pattern: Author-driven stem (guided context) → Reader-driven bowl (open exploration).
-- **How-to:** Task-focused, assumes baseline competence, minimal theory.
-- **Reference:** Fact-based, scannable tables, no narrative filler.
-- **Explanation:** Theoretical, discusses "Why," maps concepts.
+## Rules
 
-### Step 2: EPPO Initialization
+- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.
 
-Every topic must stand alone. Start with:
-- **Title:** Clear, task- or concept-focused.
-- **Context Block:** "This topic covers [X]. You should already understand [Y] and have [Z] installed."
+## Related Skills
 
-### Step 3: Information Mapping
-
-Structure the body content:
-- **Chunking:** Break large blocks into units of <7 items.
-- **Labeling:** Use headers that describe the *result* or *content* (e.g., "Configuring the API" not just "Configuration").
-- **Tables/Lists:** Convert complex comparisons or steps into visual structures.
-
-### Step 4: AI-First Polish
-
-- **Semantic Headers:** Ensure headers are descriptive for RAG indexing.
-- **Compressed Summary:** Provide a 1-2 sentence "tl;dr" at the top for LLM ingestion.
-
-## Template (How-to Guide)
-
-```markdown
-# [Task-Focused Title]
-
-**TL;DR:** [1-sentence summary for human/AI]
-
-## Context & Prerequisites
-This guide explains how to [Goal]. Before starting, ensure you have:
-- [Prerequisite 1]
-- [Prerequisite 2]
-
-## [Action Step 1: Specific Result]
-[Chunked instructions]
-
-## [Action Step 2: Specific Result]
-[Chunked instructions]
-
-## Troubleshooting: Common Fail-States
-| Symptom | Cause | Fix |
-| :--- | :--- | :--- |
-| [Error] | [Reason] | [Solution] |
-
-## Further Exploration
-- [Lateral Link 1] (Subject affinity)
-- [Lateral Link 2] (Subject affinity)
-```
+- `research-documentation` — audit before writing.
+- `review-documentation` — review after writing.

package/pi-package/skills/implement-documentation/references/anti-patterns.md

@@ -0,0 +1,35 @@
+# Documentation Anti-Patterns
+
+Avoid these during Step 1 (quadrant check) and throughout writing. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, Common Mistakes and Anti-Patterns).
+
+## Leading with explanation instead of action
+
+The engineer's impulse is to explain how a system works before showing how to use it. This is backwards for most users. Quickstart then how-to then reference is the ramp-up order. Fix: in Tutorials and How-tos, lead with a runnable result; move "how it works" to Explanation.
+
+## One stream of text serving as THE DOCS
+
+A single document trying to teach beginners, guide intermediate users, and serve as expert reference serves none of them. Fix: split by Diátaxis quadrant; each page has one intent.
+
+## FAQ lists as an anti-pattern
+
+An FAQ is "the box in the garage where you put things when you can't be bothered to put them in the right place." If information is in the right Diátaxis quadrant, it does not need repeating in an FAQ. Fix: place each answer where it belongs; delete the FAQ or keep only genuinely miscellaneous items.
+
+## The curse of knowledge
+
+Experts forget what it was like not to know. They skip "obvious" steps, use undefined jargon, assume context beginners lack. Fix: in Tutorials, state every prerequisite; define jargon on first use; have a non-expert read it.
+
+## Stale documentation
+
+Docs not embedded in the development workflow drift from the code. Incorrect docs are worse than missing docs — they waste time and erode trust. Fix: docs-as-code, docs-updated checkboxes in PRs, "you touch it, you document it."
+
+## Knowledge silos
+
+Scattered docs across wikis, READMEs, Confluence, Notion create a fragmented experience where users cannot find things and contributors do not know where to put new content. Fix: one canonical location, ideally in the same repo as the code.
+
+## Partial coverage
+
+Documenting some but not all of a feature or API creates a false sense of completeness — users assume the undocumented part does not exist or work. Fix: cover a concept fully or not at all; use the completeness checklist (in the `research-documentation` skill's `references/checklist.md`).
+
+## Mixed-intent "Frankenbooks"
+
+A page that starts as a tutorial, becomes reference, and ends as explanation. Fix: split into three focused pages; each keeps quadrant purity. Use a Note or Deep Dive sidebar only when a sliver of theory is required inside a task page.

package/pi-package/skills/implement-documentation/references/diataxis-implementation.md

@@ -0,0 +1,31 @@
+# Diátaxis Implementation Guide
+
+Six-step rollout for adopting Diátaxis on an existing or new documentation set. Use in Step 5 when the task is a full architecture rollout rather than a single topic. The Diátaxis framework theory is canonical in `content/research-documentation-frameworks.md`; these implementation steps are sourced from `content/research-finding-library-docs-best-practices.md` (Section 3, How to Implement Diátaxis in Practice).
+
+## Step 1: Audit existing documentation
+
+Catalog every existing document and classify it as Tutorial, How-to, Reference, or Explanation. The audit typically reveals that most docs are reference, with gaps in tutorials and explanation. (Use the `research-documentation` skill for this.)
+
+## Step 2: Create a directory structure
+
+Create four directories or sections: `tutorials/`, `how-to/` (or `guides/`), `reference/`, and `explanation/`. Apply title conventions per type: Explanation titles use "Understanding / Dive into / Introduction to..."; How-to titles start with "How to..."; Tutorial titles use "Getting started with...".
+
+## Step 3: Assign content types and split mixed documents
+
+Long mixed-topic documents become multiple short, focused documents. A document that is tutorial then reference then explanation becomes three separate documents, each in its quadrant directory.
+
+## Step 4: Establish contribution guidelines
+
+Document the framework for contributors so new docs land in the right place from the start. Without guidelines the four-directory structure fills with misclassified content. Keep the guidelines short: one sentence per quadrant on what belongs there.
+
+## Step 5: Integrate with the development workflow
+
+Add architecture specs to Reference alongside code changes. Add technical decision logs to Explanation during feature development. Docs-updated checkboxes in PR templates. This integration is what keeps docs current.
+
+## Step 6: Use Diátaxis as an AI prompt template
+
+The clear information patterns make effective AI prompt templates: ask a model to sort unstructured content into the four patterns to accelerate a first draft, then review and refine. (See `templates.md` for the per-quadrant output shapes.)
+
+## Critiques to keep in mind
+
+Diátaxis is a guide, not dogma. Forcing every artifact into four rigid buckets produces awkward docs. The terms overlap (tutorial vs. how-to needs editorial judgment). The framework does not address content reuse (DITA's conref may suit enterprise multi-output needs) nor finding aids. For early-stage projects, a single compelling quick start may suffice before the full suite.