incitaciones 0.3.0 → 0.3.2

package/pi-package/skills/implement-documentation/references/templates.md

@@ -0,0 +1,115 @@
+# Diátaxis Templates
+
+One template per quadrant. Match the template to the quadrant identified in Step 1. The canonical theory is `content/research-documentation-frameworks.md`.
+
+## Tutorial (learning-oriented, beginners)
+
+Goal: build competency through a guided, safe experience. Show, do not lecture.
+
+```markdown
+# [Getting Started with X]
+
+**TL;DR:** [1-sentence outcome for human/AI]
+
+## What You Will Learn
+By the end you will have [concrete result]. No prior knowledge of [X] is assumed.
+
+## Prerequisites
+- [Prerequisite 1]
+- [Prerequisite 2]
+
+## Step 1: [Specific Result]
+[Chunked, do-this-now instructions. Each step yields a visible result.]
+
+## Step 2: [Specific Result]
+[Chunked instructions.]
+
+## Recap & Next Steps
+You built [X]. Next, try [lateral link 1] or [lateral link 2].
+```
+
+## How-to (task-oriented, assumes baseline competence)
+
+Goal: answer a specific question directly. Minimal theory.
+
+```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)
+```
+
+## Reference (information-oriented, experienced users)
+
+Goal: fast, accurate facts. Scannable tables, no narrative filler.
+
+```markdown
+# [X] Reference
+
+**TL;DR:** [1-sentence summary for human/AI]
+
+## [Function/Endpoint/Class Name]
+
+**Signature:** `signature`
+
+**Parameters:**
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| [name] | [type] | yes/no | [description] |
+
+**Returns:** [type and meaning]
+
+**Errors:**
+| Code | Meaning | Remediation |
+| :--- | :--- | :--- |
+| [code] | [meaning] | [fix] |
+
+**Example:**
+[Minimal, complete, runnable example]
+```
+
+## Explanation (understanding-oriented, the "why")
+
+Goal: deepen knowledge; no specific task. Discussion, design rationale, trade-offs.
+
+```markdown
+# [Understanding X]
+
+**TL;DR:** [1-sentence summary for human/AI]
+
+## Why [X] Exists This Way
+[Design rationale and history. No steps.]
+
+## Key Concepts
+- [Concept 1]: [definition and why it matters]
+- [Concept 2]: [definition and how it relates to Concept 1]
+
+## Trade-offs
+| Approach | Pro | Con |
+| :--- | :--- | :--- |
+| [A] | [pro] | [con] |
+| [B] | [pro] | [con] |
+
+## Further Exploration
+- [Lateral Link 1] (Subject affinity)
+- [Lateral Link 2] (Subject affinity)
+```

package/pi-package/skills/implement-documentation/references/tooling-comparison.md

@@ -0,0 +1,46 @@
+# Tooling Comparison & Docs-as-Code
+
+Use in Step 5 when choosing a platform or setting up docs infrastructure. Platform selection is an implementation decision, not an audit finding. Source: `content/research-finding-library-docs-best-practices.md` (Section 6, Modern Tooling and Infrastructure).
+
+## Platform comparison
+
+| Platform | Best For | Stack | Key Strength |
+| :--- | :--- | :--- | :--- |
+| Docusaurus | Complex OSS docs, versioning | React/JS | Ecosystem, versioning, MDX |
+| MkDocs (Material) | Python projects, simple setup | Python | Simplicity, polished theme |
+| Sphinx | Python API reference | Python | Autodoc, multiple outputs |
+| Read the Docs | OSS hosting, versioning | Agnostic | Free hosting, versioning |
+| GitBook | Team knowledge bases | Agnostic | Editing UX, AI search |
+| Mintlify | API docs, dev portals | Agnostic | Design, AI search, OpenAPI |
+| Starlight | Performance-critical docs | Astro | Performance, accessibility |
+| Nextra | Custom Next.js sites | React/Next.js | Customization, React components |
+
+## How to choose
+
+- Python ecosystem or simplicity: MkDocs / Sphinx.
+- API reference that must stay synced to code: Sphinx autodoc, mkdocstrings, or TypeDoc.
+- API docs with interactive playground: Mintlify.
+- Complex OSS docs with versioning and i18n: Docusaurus.
+- Performance and built-in accessibility: Starlight.
+- Free open-source hosting with versioning: Read the Docs.
+
+## Docs-as-code workflow
+
+Write docs in plain text (Markdown/AsciiDoc/reST), store in Git, review through pull requests, publish through CI/CD. Core practices:
+
+- Store docs in the same repository as the code.
+- Write in plain text (Markdown dominates for developer docs).
+- Review all doc changes through the same PR process as code.
+- Automate builds and deployments via CI/CD (GitHub Actions, GitLab CI).
+- Enforce quality through automation: Vale, markdownlint, link checkers (htmlproofer, lychee), spell checkers on every PR.
+- Generate API reference from OpenAPI/Swagger to keep it synchronized.
+
+## Specification-driven API docs
+
+- **OpenAPI** is the standard for REST APIs (YAML/JSON). Use it to auto-generate interactive reference (Swagger UI, Redoc, Stoplight Elements), client SDKs, and mock servers, and to power AI agent tool manifests.
+- **AsyncAPI** extends the approach to event-driven APIs (WebSockets, Kafka, MQTT).
+- Prefer a **design-first** approach: write the spec before the code. This enables early collaboration, immediate mock servers, and ensures docs are never an afterthought.
+
+## Interactive documentation
+
+Place the interactive element directly adjacent to the relevant docs, not on a separate playground page. Live code playgrounds (CodeSandbox, StackBlitz), interactive API explorers (Swagger UI, Mintlify), and embedded REPLs reduce time-to-first-success.

package/pi-package/skills/implement-documentation/references/versioning.md

@@ -0,0 +1,31 @@
+# Versioning & Changelog Strategy
+
+Use in Step 5 when setting up versioned documentation. Source: `content/research-finding-library-docs-best-practices.md` (Section 2, Versioned Documentation Strategies).
+
+## Version-tagged documentation
+
+Each major release should have a corresponding docs version. Tools like Read the Docs, Docusaurus, and Sphinx provide built-in versioned docs so users can select the version matching their installed software.
+
+## Version selector in the UI
+
+A prominent version selector in navigation lets users switch versions. The current stable version is the default, with clear indicators when a user is viewing an older or pre-release version.
+
+## Deprecation notices
+
+When features are deprecated, update docs immediately with a deprecation notice, the version in which deprecation occurred, and a migration path to the replacement.
+
+## Changelog as a first-class document
+
+Treat the changelog as a primary artifact, not an afterthought. Link it prominently from the docs home page and update it as part of the release process. Link migration guides from the changelog entries that introduce breaking changes; highlight breaking changes prominently.
+
+## Write version-agnostic content where possible
+
+Conceptual and explanation content that does not change between versions should avoid version-specific references. This reduces maintenance burden and prevents confusion.
+
+## Docs-as-code for version control
+
+Store docs in the same Git repository as the code (or a closely linked one) so docs version alongside code. Pull requests for code changes include doc updates; CI/CD pipelines can enforce that docs are updated before a release merges.
+
+## Canonical URLs
+
+Versioned docs create a risk of duplicate-content search penalties. Use canonical URL tags pointing search engines to the current stable version of each page.

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

@@ -14,16 +14,17 @@ tools: Read, Write, Edit, Bash
 
 Snapshot the current session's work on a project/area before switching context. This is NOT end-of-day — just a context switch.
 
-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. Get today's date and current time (`date +%Y-%m-%d`, `date +%H:%M`).
    ```bash
    JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
    ```
 
-2. Read today's log: `$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`
+2. Read today's log: `$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`
    If it doesn't exist, create it with the daily log template.
 
 3. Review the conversation history to determine:

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

@@ -14,13 +14,14 @@ tools: Read, Write, Edit, Glob, Bash, Grep
 
 Load focused context for a specific project or area to continue work.
 
-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
    ```
 
@@ -43,13 +44,13 @@ Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log, and `~/.whi
 
 3. Read the matched project or area file.
 
-4. Read today's log (`$JOURNAL/log/YYYY/YYYY-MM/YYYY-MM-DD.md`).
+4. Read today's log (`$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`).
    If it doesn't exist, create it with the daily log template.
    Scan for any earlier session entries related to this project/area today.
 
 5. Search recent logs for context (last 3 days):
    ```bash
-   grep -rl "<slug>" "$JOURNAL"/log/YYYY/YYYY-MM/ 2>/dev/null | tail -3
+   grep -rl "<slug>" "$JOURNAL"/"$LOG_SUBDIR"/YYYY/YYYY-MM/ 2>/dev/null | tail -3
    ```
    Read any matches to understand recent session history.
 

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

@@ -6,80 +6,30 @@ metadata:
 ---
 # Research Documentation Architecture
 
-Audit the existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
+Audit existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
 
-## CRITICAL RULES
+## Core 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).
+- You are an architect, not a writer. Map structure and gaps; do not draft content.
 
-## Process
+## Procedure
 
-### Step 1: Define the Scope
+1. Define the scope: identify the primary audience (novice vs. expert) and state the single-sentence "Core Assertion" (the value proposition). If existing docs have conflicting hooks, pick the most impactful or propose a synthesis.
+2. Analyze existing content (if any): for each file determine its Diátaxis quadrant, EPPO status (standalone utility), and cognitive load. Use `references/checklist.md` for the completeness and accessibility items to check against.
+3. Map the Snowflake outline: Core Assertion, Macro-Expansion, Component List, Topic Matrix by quadrant.
+4. Identify gaps and friction: quadrant imbalance, structural plot-holes, and AI-readiness gaps. Use `references/llm-readiness.md` to assess `llms.txt`, MCP, RAG chunking, and dual-audience design. Use `references/metrics.md` to recommend measurement signals (TTFS, search analytics, coverage, freshness).
+5. Produce the final research report using `references/report-template.md`.
 
-[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.
+## Rules
 
-### Step 2: Audit Existing Content (if applicable)
+- Categorize every document into exactly one Diátaxis quadrant.
+- Flag "Frankenbooks" (documents with mixed intent/quadrants).
+- Verify EPPO compliance: does each page establish its own context?
+- Do not start writing content; focus on architecture and gaps.
+- Do not suggest stylistic changes; focus on structural integrity.
+- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.
 
-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?
+## Related Skills
 
-### 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]
-```
+- `implement-documentation` — write topics from this audit.
+- `review-documentation` — review what you write.

package/pi-package/skills/research-documentation/references/checklist.md

@@ -0,0 +1,58 @@
+# Documentation Completeness Checklist
+
+Use during the audit (Step 2) to check existing or planned coverage. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, the best-practices checklist, and Section 5, accessibility).
+
+## Completeness and accuracy
+
+- All public APIs, endpoints, parameters, and return values are documented.
+- All error codes and messages are documented with explanations and remediation steps.
+- Prerequisites and system requirements are stated upfront.
+- All code examples are tested and verified to work with the current version.
+- No documented features are missing from the implementation, and no undocumented features exist.
+
+## Getting started and onboarding
+
+- A "Getting Started" or "Quick Start" guide exists and can be completed in under 15 minutes.
+- The guide leads to a meaningful, working result (not just "Hello, World" unless that is genuinely useful).
+- Installation instructions cover all supported platforms and package managers.
+- Authentication and configuration are explained before any API calls are shown.
+
+## API reference
+
+- Each endpoint/function/method has a human-friendly description, not just a parameter list.
+- Request and response examples are provided for every endpoint.
+- Authentication requirements are documented per endpoint where relevant.
+- Rate limits, pagination, and other operational constraints are documented.
+- The reference is generated from or synchronized with a machine-readable specification (OpenAPI, TypeDoc, JSDoc, Sphinx autodoc).
+
+## Versioning and changelog
+
+- Documentation is versioned to match software releases.
+- A changelog exists and is kept up to date.
+- Breaking changes are prominently highlighted.
+- Deprecated features are marked with migration paths provided.
+- Old versions of documentation remain accessible.
+
+## Code examples
+
+- Examples exist for all major use cases.
+- Examples are provided in all officially supported languages/frameworks.
+- Examples are complete and runnable, not pseudocode or partial snippets.
+- Examples follow current best practices and idioms for each language.
+
+## Conceptual and explanatory content
+
+- Architecture and design decisions are explained (the "why", not just the "what").
+- Key concepts are defined before they are used.
+- Diagrams and visuals are used where they clarify complex relationships.
+
+## Accessibility (WCAG 2.1 AA)
+
+- Code syntax highlighting meets minimum contrast ratios.
+- All navigation, search, and interactive elements are operable by keyboard alone.
+- Code blocks, tables, and diagrams have appropriate ARIA labels and alt text.
+- The site is readable on mobile and manages focus correctly in single-page-app navigation.
+
+## Out of scope for this checklist
+
+Internationalization/localization and interactive documentation (live playgrounds, API explorers) are valid concerns but are tracked separately as platform/infrastructure decisions, not architectural-audit items.

package/pi-package/skills/research-documentation/references/llm-readiness.md

@@ -0,0 +1,43 @@
+# LLM & Agentic Readiness Reference
+
+Operational excerpt for the AI-readiness gap assessment in Step 4. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability"); this file distills the concrete checks.
+
+## `llms.txt` standard
+
+An emerging convention analogous to `robots.txt`: a machine-readable index at the docs site root that tells LLMs which pages matter most, with structured summaries. Check:
+
+- Is a `llms.txt` present at the documentation root?
+- Does it list the most authoritative pages (quick start, API reference, key how-tos)?
+- Are summaries concise and current with the latest version?
+
+## RAG-friendly chunking
+
+Documentation structured as single-topic, self-contained modules chunks cleanly for retrieval-augmented generation. Check:
+
+- Does each page cover one well-defined topic (Diátaxis quadrant purity enables this)?
+- Are pages small enough to be one RAG chunk, or do they need explicit section anchors?
+- Is there redundant cross-page duplication that would pollute retrieval?
+
+## MCP and agent manifests
+
+For tooling/agent documentation, the description fields are documentation. Check:
+
+- Are MCP tool manifests present with precise `name`, `description`, input/output JSON schemas?
+- Are plugin/agent cards machine-readable with capability boundaries and error conditions?
+- Is language precise enough for a machine (no context-dependent ambiguity a human would resolve but an agent would not)?
+
+## Dual-audience design
+
+Modern docs serve human readers and machine consumers. The practices that serve both: clear structure, consistent terminology, modular organization, explicit metadata. Check:
+
+- Are headings semantic and unique (not generic "Overview" repeated across pages)?
+- Is front matter present (title, description, version, category)?
+- Are API references generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
+
+## Docs-as-context
+
+Documentation is increasingly a runtime input to AI systems (system-prompt embedding, RAG retrieval, vector search). Check:
+
+- Is clean, navigation-chrome-free text available for context-window injection?
+- Are code examples complete and runnable (agents execute what they read)?
+- Is terminology consistent so a model trained on the docs retrieves accurately?

package/pi-package/skills/research-documentation/references/metrics.md

@@ -0,0 +1,42 @@
+# Documentation Quality Metrics
+
+Use in Step 4 to recommend measurement signals. The single most important metric is time-to-first-success; the rest build the feedback loops that keep docs honest. Source: `content/research-finding-library-docs-best-practices.md` (Section 7, Measuring Documentation Quality).
+
+## Key metrics
+
+- **Time-to-first-success (TTFS).** Time from a developer's first encounter with the docs to their first successful use of the library/API. Measure via user testing, analytics (first page view to first successful API call), or surveys. This is the headline number.
+- **Support ticket deflection.** Percentage of support questions answered by docs rather than a human. Quantifies economic value; track the ratio of tickets to page views, or add "Did this page answer your question?" widgets.
+- **Page engagement.** Time on page, scroll depth, return visits. High bounce on getting-started may mean unmet expectations; low time on reference may mean fast finds (good) or frustration (context matters).
+- **Search analytics.** Track queries, click-through rates, and "no results" queries. No-results queries are direct evidence of missing docs. High click-through to a page means it is well-titled and relevant.
+- **Broken link rates.** Percentage of internal/external links returning 404. Automated link checking should run on every deployment (see `doc-link-verifier` skill).
+- **Documentation coverage.** Percentage of public APIs/endpoints/features that have docs. Measurable automatically for API reference (OpenAPI vs. documented endpoints) and code docs (docstring coverage via `interrogate`).
+- **Page freshness.** Age of a doc page relative to the last code change that touched the documented feature. Stale docs are a leading frustration indicator.
+
+## User testing and feedback loops
+
+- **Usability testing.** Watch representative users attempt tasks using only the docs. Even informal tests reveal problems invisible to authors.
+- **Inline feedback widgets.** "Was this page helpful?" at the bottom of pages. Act on it: low-rated pages get prioritized.
+- **GitHub issues and discussions.** Questions already answered in docs indicate the docs are not discoverable or clear enough.
+- **Developer surveys.** Periodic structured feedback on quality, gaps, and priorities.
+- **Community channels.** Repeated questions in Discord/Slack/Stack Overflow are strong gap signals.
+
+## Automated quality tools (CI/CD)
+
+- **Vale** — prose linter enforcing style-guide rules (passive voice, jargon, inconsistent terminology).
+- **markdownlint** — Markdown formatting consistency.
+- **htmlproofer / lychee** — internal and external link checking on every deployment.
+- **interrogate** (Python) — docstring coverage reporting.
+- **cspell / aspell** — spell checking.
+- **Lighthouse** — page performance, accessibility, SEO, best practices in CI.
+
+A practical pipeline: on every PR run markdownlint + Vale + cspell + example tests; on every deployment run link checking + Lighthouse; weekly run a full broken-link crawl, coverage report, and freshness report; monthly review user feedback and search analytics.
+
+## Building a quality culture
+
+Metrics are necessary but not sufficient. Culture is the larger factor:
+
+- Add "docs updated" checkboxes to PR templates.
+- Allocate explicit sprint time (15-20%) to documentation and refactoring.
+- Apply "you touch it, you document it" — the author of a code change owns the doc update.
+- Assign a named owner to every documentation section.
+- Celebrate documentation contributions the same way as code contributions.

package/pi-package/skills/research-documentation/references/report-template.md

@@ -0,0 +1,42 @@
+# Documentation Research Report Template
+
+Output structure for the final report (Step 5). Keep the section order stable so reports can be compared across projects.
+
+```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/agent manifests identified?
+
+## 6. Measurement Signals
+- [ ] TTFS measurable today?
+- [ ] Search analytics available?
+- [ ] Coverage / freshness tracked?
+
+## 7. Recommended Next Steps
+1. [Actionable structural change]
+2. [Actionable topic creation]
+3. [Actionable measurement setup]
+```

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

@@ -8,43 +8,48 @@ metadata:
 
 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.**
+## Core Rules
+
+- You are a reviewer, not a writer. Flag issues with locations; do not rewrite content.
+
+## Procedure
+
+Perform 5 iterative passes. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged.
+
+### 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 under 10 seconds and find the key answer? Checks: are descriptive labels used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are tables and lists used for complex data? Issue prefix: [SCAN-001].
+
+### Pass 4: Accuracy, "Whole Game" & Fail-States
+
+Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open 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) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001].
+
+## Final Report
+
+- Total Issues by Severity (Critical, High, Medium, Low).
+- Top 3 Findings.
+- Verdict: Ready, Needs Revision, or Needs Rework.
+- Rationale.
+
+## Rules
+
+- Reference exact locations (file, section, paragraph).
+- Validate issues exist; do not flag "potential" issues without evidence.
+- The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it.
+
+## Related Skills
+
+- `research-documentation` — architecture-level gaps.
+- `implement-documentation` — fixing what the review finds.