incitaciones 0.3.0 → 0.3.1

package/pi-package/skills/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/distilled/implement-documentation.md

@@ -1,68 +0,0 @@
-# Implement Documentation Topic
-
-Write a high-signal documentation topic using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL 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).
-
-## Implementation Workflow
-
-### Step 1: Quadrant Check
-
-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.
-
-### Step 2: EPPO Initialization
-
-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."
-
-### 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)
-```

package/content/distilled/research-documentation.md

@@ -1,79 +0,0 @@
-# Research Documentation Architecture
-
-Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
-
-## CRITICAL RULES
-
-1. ✅ **DO:** Categorize every document into exactly one Diátaxis quadrant.
-2. ✅ **DO:** Identify "Frankenbooks" (documents with mixed intent/quadrants).
-3. ✅ **DO:** Map the "Snowflake" progression from Core Assertion to granular topics.
-4. ✅ **DO:** Verify EPPO compliance (Does each page establish its own context?).
-5. ❌ **DO NOT:** Start writing content yet; focus on architecture and gaps.
-6. ❌ **DO NOT:** Suggest stylistic changes (focus on structural integrity).
-
-## Process
-
-### Step 1: Define the Scope
-
-[User will provide a path to a documentation directory or a project description.]
-- Identify the primary audience (Novice vs. Expert).
-- State the "Core Assertion" (The single-sentence value proposition).
-- **Legacy Conflict Resolution:** If existing documentation contains multiple, conflicting "hooks," identify the most impactful one or propose a synthesis for the new architecture.
-
-### Step 2: Audit Existing Content (if applicable)
-
-For each file in the directory, determine:
-- **Quadrant:** (Tutorial | How-to | Reference | Explanation).
-- **EPPO Status:** (Pass/Fail) Does it have standalone utility and context?
-- **Cognitive Load:** Are there "walls of words" or missing labels?
-
-### Step 3: Map the Snowflake Outline
-
-Expand the Core Assertion into a structural map:
-1. **Core Assertion:** [1 sentence]
-2. **Macro-Expansion:** [1 paragraph user journey]
-3. **Component List:** [The "characters" of the system]
-4. **Topic Matrix:** A list of proposed EPPO topics categorized by quadrant.
-
-### Step 4: Identify Gaps and Friction
-
-- **Quadrant Imbalance:** e.g., "Too much reference, not enough tutorials."
-- **Structural Plot-holes:** Where does the user journey break?
-- **AI-Readiness Gaps:** Missing `llms.txt`, poor semantic labeling.
-
-### Step 5: Final Research Report
-
-Output the audit/plan using the following template:
-
-```markdown
-# Documentation Research: [Project Name]
-
-## 1. Executive Summary & Core Assertion
-**Core Assertion:** [The one-sentence hook]
-**Status:** [Summary of current architecture health]
-
-## 2. Diátaxis Matrix
-| Quadrant | Existing Topics | Proposed/Missing Topics |
-| :--- | :--- | :--- |
-| **Tutorial** | | |
-| **How-to** | | |
-| **Reference** | | |
-| **Explanation** | | |
-
-## 3. Snowflake Structural Map
-- **Macro-Journey:** [Description]
-- **Key Components:** [List]
-
-## 4. EPPO & Cognitive Audit
-- **Frankenbooks Found:** [List of files with mixed intent]
-- **Context Gaps:** [Topics needing better orientation]
-
-## 5. AI-Readiness Assessment
-- [ ] `llms.txt` present?
-- [ ] Explicit semantic labeling for RAG?
-- [ ] MCP endpoints identified?
-
-## 6. Recommended Next Steps
-1. [Actionable structural change]
-2. [Actionable topic creation]
-```

package/content/distilled/review-documentation.md

@@ -1,44 +0,0 @@
-# Review Documentation Quality
-
-Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.
-
-## REVIEW PROCESS
-
-Perform 5 iterative passes, checking for convergence after each pass (starting with pass 2).
-
-### PASS 1: Diátaxis & Intent
-- **Goal:** Does this topic have a single, clear intent?
-- **Checks:** Is it a Tutorial, How-to, Reference, or Explanation? Are there "leaked" intents? (e.g., too much theory in a Tutorial).
-- **Issue Prefix:** [INTENT-001]
-
-### PASS 2: EPPO & Standalone Utility
-- **Goal:** Can a "foraging" reader land here and succeed?
-- **Checks:** Are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links?
-- **Issue Prefix:** [EPPO-001]
-
-### PASS 3: Cognitive Scannability (Info Mapping)
-- **Goal:** Can the reader scan the page in <10 seconds and find the key answer?
-- **Checks:** Are **labels** (descriptive headers) used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are there tables/lists for complex data?
-- **Issue Prefix:** [SCAN-001]
-
-### PASS 4: Accuracy, "Whole Game" & Fail-States
-- **Goal:** Is the content technically sound and resilient?
-- **Checks:** Are the code snippets/math verified? Does it show the "Whole Game" (complete result)? Are common errors (fail-states) documented? In tutorials, is the **Martini Glass** pattern followed (context → exploration)?
-- **Issue Prefix:** [ACC-001]
-
-### PASS 5: Excellence & AI-Readiness
-- **Goal:** Is it production-ready and optimized for AI agents?
-- **Checks:** Is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the **Answer First** (Pyramid Principle) located in the TL;DR and first paragraph?
-- **Issue Prefix:** [EXCL-001]
-
-## Convergence Check
-After each pass (starting with pass 2), report:
-- Total new issues found.
-- Estimated "Signal-to-Noise" ratio.
-- Convergence status: (CONVERGED | CONTINUE).
-
-## Final Report Format
-- **Total Issues by Severity** (Critical | High | Medium | Low).
-- **Top 3 Findings.**
-- **Verdict:** (Ready | Needs Revision | Needs Rework).
-- **Rationale.**