@vpxa/aikit 0.1.63 → 0.1.65

package/scaffold/general/skills/docs/references/diataxis-compass.md

@@ -0,0 +1,123 @@
+# The Diataxis Compass
+
+The Diataxis Compass is a simple classification aid for documentation. It reduces classification to two axes so an author can decide what kind of document they are writing before structure and tone drift across quadrants.
+
+Use it when a draft feels mixed, when a request could fit more than one documentation type, or when you need a quick check before creating a new document.
+
+## The Two Axes
+
+The compass uses two independent axes:
+
+| Axis | Question | Poles | What it tells you |
+|------|----------|-------|-------------------|
+| Horizontal | Is the reader trying to do something or understand something? | Action vs Cognition | Whether the content should guide behavior or develop understanding |
+| Vertical | Is the reader learning or working? | Study vs Work | Whether the content serves acquisition or application |
+
+Interpret the axes this way:
+
+- **Action** means practical doing, following steps, executing work, or completing a task.
+- **Cognition** means understanding, context, concepts, relationships, or meaning.
+- **Study** means the reader is acquiring skill or knowledge.
+- **Work** means the reader is applying skill or knowledge to a real task.
+
+## ASCII Quadrant Diagram
+
+```text
+                     ACTION                              COGNITION
+          +--------------------------------+--------------------------------+
+ STUDY    | Tutorial                       | Explanation                    |
+          | Learn by doing                 | Learn by understanding         |
+          +--------------------------------+--------------------------------+
+ WORK     | How-to Guide                   | Reference                      |
+          | Accomplish a specific task     | Consult facts while working    |
+          +--------------------------------+--------------------------------+
+```
+
+## Two-Question Decision Tree
+
+Ask these questions in order:
+
+1. Is the reader trying to **DO** something or **UNDERSTAND** something?
+2. Is the reader **LEARNING** or **WORKING**?
+
+Answer matrix:
+
+| Q1 | Q2 | Result |
+|----|----|--------|
+| Action | Study | Tutorial |
+| Action | Work | How-to guide |
+| Cognition | Work | Reference |
+| Cognition | Study | Explanation |
+
+Short version:
+
+- Action + Study = **Tutorial**
+- Action + Work = **How-to guide**
+- Cognition + Work = **Reference**
+- Cognition + Study = **Explanation**
+
+## Content Type Signals
+
+Trigger phrases are not absolute rules, but they are strong signals.
+
+| Quadrant | Typical trigger phrases or patterns | What they usually indicate |
+|----------|-------------------------------------|----------------------------|
+| Tutorial | `build your first`, `getting started`, `learn`, `introduction to`, `beginner`, `walkthrough` | A guided learning path with a defined outcome |
+| How-to guide | `how to`, `configure`, `deploy`, `set up`, `integrate`, `migrate`, `troubleshoot` | A task-focused guide for a user trying to solve a real problem |
+| Reference | `API`, `parameters`, `options`, `schema`, `configuration`, `specification`, `returns` | Structured factual material consulted during work |
+| Explanation | `why`, `how it works`, `overview`, `trade-offs`, `background`, `concepts`, `design` | Material meant to increase understanding and context |
+
+Signals become more reliable when they align across title, headings, verbs, and document structure.
+
+## Confidence Calibration
+
+Use confidence to decide whether to classify, split, or rewrite.
+
+| Confidence | Interpretation | Recommended action |
+|------------|----------------|--------------------|
+| High | All signals match one quadrant | Classify directly and write fully in that mode |
+| Medium | Signals match one quadrant but the topic could span two | Classify to the dominant quadrant and cross-link the adjacent need |
+| Low | Mixed signals across quadrants | Split the document rather than forcing one label |
+
+Practical rule:
+
+- **High** means title, tone, structure, and user need all point the same way.
+- **Medium** means one quadrant clearly dominates, but a neighboring quadrant is tempting.
+- **Low** means the document is trying to teach, guide, explain, and describe at once.
+
+## Edge Cases
+
+Some common document labels are ambiguous on their face. Classify by function, not by title alone.
+
+| Content label | Recommended classification | Reasoning |
+|---------------|----------------------------|-----------|
+| README | Reference | Usually a project summary and entry point, not a discursive explanation |
+| FAQ | Split per question | Each answer may belong to a different quadrant |
+| Getting Started | Tutorial or How-to guide | Tutorial if aimed at learning; How-to if aimed at competent users getting started in work |
+| Troubleshooting | How-to guide | It is task-oriented problem solving |
+| Changelog | Reference | It is a factual record |
+| Architecture overview | Explanation | It exists to help the reader understand system design |
+| Migration guide | How-to guide | It helps the reader complete a concrete transition task |
+
+## Ambiguity Protocol
+
+When classification is uncertain:
+
+1. Default to the quadrant that serves the reader's immediate need.
+2. If it is still unclear, split the document by quadrant.
+3. If splitting is not worth the cost, classify it by the dominant quadrant and explicitly note the secondary one.
+
+Useful signs that a split is warranted:
+
+- the introduction promises learning, but the body is a task checklist
+- the document alternates between step-by-step actions and API facts
+- the writer keeps adding “why” digressions to operational instructions
+- headings naturally group into two different quadrant modes
+
+## Attribution
+
+This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the Compass and related quadrant descriptions.
+
+Source material is licensed under **CC-BY-SA 4.0**.
+
+Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).

package/scaffold/general/skills/docs/references/diataxis-quadrants.md

@@ -0,0 +1,192 @@
+# Diataxis Quadrants
+
+This reference describes the four documentation quadrants in Diataxis: Tutorial, How-to guide, Reference, and Explanation. Use it when a document has already been classified, or when you need boundary tests to decide whether content belongs in one quadrant or has drifted into another.
+
+## Tutorial
+
+### Definition
+
+A tutorial is a guided learning experience. It helps a reader acquire competence by doing something meaningful in a controlled path toward a defined outcome.
+
+### Tutorial Is / Is Not
+
+| IS | IS NOT |
+|----|--------|
+| Learning-oriented | A reference to consult |
+| Practical and guided | A set of independent steps |
+| Structured as a path | Complete coverage of a topic |
+| Built around a defined outcome | A free-form discussion |
+
+### Defining Characteristics
+
+- It is designed for a reader who is still learning.
+- It follows a deliberate path from start to finish.
+- It creates a successful encounter with the product or skill.
+- It limits choices so the learner can focus.
+- It optimizes for confidence, momentum, and visible progress.
+
+### Language Patterns
+
+Tutorial language is guided, concrete, and supportive. It commonly uses second person and first-person plural.
+
+- `In this tutorial, you will ...`
+- `You'll see ...`
+- `Next, we ...`
+- `Notice that ...`
+- `The output should look something like ...`
+
+The tone should reduce uncertainty, set expectations, and keep the learner on a single path.
+
+### Boundary Tests
+
+- If the steps can be done in any order, it is probably **not** a tutorial.
+- If there is no learning outcome, it is probably a **How-to guide**.
+- If the content starts listing all options and variants, it is drifting toward **Reference**.
+- If the content spends time on rationale and design history, it is drifting toward **Explanation**.
+
+## How-to Guide
+
+### Definition
+
+A how-to guide is a task-oriented document for someone trying to solve a specific problem or complete a real piece of work. It assumes the reader already has enough competence to act on concise guidance.
+
+### How-to Is / Is Not
+
+| IS | IS NOT |
+|----|--------|
+| Task-oriented | A lesson |
+| Practical | An explanation of concepts |
+| Focused on a specific problem | A comprehensive reference |
+| Written for application in real work | A broad introduction |
+
+### Defining Characteristics
+
+- It starts from a concrete goal or problem.
+- It is written for readers who are already doing work.
+- It emphasizes action, judgement, and usable sequence.
+- It avoids digressions into fundamentals unless strictly necessary.
+- It may branch for real-world conditions and alternatives.
+
+### Language Patterns
+
+How-to language is direct and imperative. It should sound executable.
+
+- `Configure X.`
+- `Deploy to Y.`
+- `Set up the service account.`
+- `If you need Z, do ...`
+- `To migrate safely, first ...`
+
+Good how-to writing is short, concrete, and free of conceptual detours.
+
+### Boundary Tests
+
+- If it teaches fundamentals before the task, it is drifting toward **Tutorial**.
+- If it mostly describes available options rather than choosing a path, it is drifting toward **Reference**.
+- If it answers `why` more than `what to do`, it is drifting toward **Explanation**.
+- If success depends on following a pedagogical sequence rather than solving a task, it belongs in **Tutorial**.
+
+## Reference
+
+### Definition
+
+Reference is factual documentation consulted during work. It describes the machinery, interface, structure, or behavior of the system as clearly and consistently as possible.
+
+### Reference Is / Is Not
+
+| IS | IS NOT |
+|----|--------|
+| Information-oriented | A guide |
+| Austere and factual | Opinionated |
+| Comprehensive within scope | Narrative |
+| Structured consistently | Selective in the style of a lesson |
+
+### Defining Characteristics
+
+- It is optimized for lookup, not for linear reading.
+- It presents facts, interfaces, constraints, and structure.
+- It uses a consistent pattern so readers can find answers quickly.
+- It aims for completeness inside a defined scope.
+- It avoids persuasion, instruction-heavy flow, and discursive context.
+
+### Language Patterns
+
+Reference language is descriptive, factual, and usually third person.
+
+- `Returns {type}.`
+- `Accepts the following parameters ...`
+- `Option values are ...`
+- `The schema contains ...`
+- `Configuration keys include ...`
+
+Warnings and constraints are fine, but they should remain factual rather than tutorial or argumentative.
+
+### Boundary Tests
+
+- If the content explains why a design exists, it belongs in **Explanation**.
+- If the content shows how to accomplish a task with the feature, it belongs in **How-to guide**.
+- If the content walks a newcomer through a first success path, it belongs in **Tutorial**.
+- If the content becomes selective and outcome-driven rather than complete and structured, it is no longer pure reference.
+
+## Explanation
+
+### Definition
+
+Explanation is understanding-oriented documentation. It connects concepts, provides rationale and background, and helps the reader build a mental model of the system or topic.
+
+### Explanation Is / Is Not
+
+| IS | IS NOT |
+|----|--------|
+| Understanding-oriented | Step-by-step instructions |
+| Discursive and connective | A lookup table |
+| Rich in context | A tutorial |
+| Concerned with reasons and implications | A terse list of facts |
+
+### Defining Characteristics
+
+- It provides context, rationale, and conceptual framing.
+- It connects details into a broader mental model.
+- It can discuss trade-offs, history, alternatives, and design intent.
+- It supports reflection more than immediate action.
+- It is bounded by topic rather than by task or API surface.
+
+### Language Patterns
+
+Explanation language is descriptive, interpretive, and often comparative.
+
+- `The reason for ...`
+- `This approach was chosen because ...`
+- `Consider the trade-off ...`
+- `Historically, the system evolved this way because ...`
+- `An X in this system is analogous to ...`
+
+It is acceptable here to surface perspective, evaluation, and multiple interpretations.
+
+### Boundary Tests
+
+- If the document has numbered operational steps, it likely belongs in **How-to guide** or **Tutorial**.
+- If it lists facts without context, it likely belongs in **Reference**.
+- If it promises a concrete outcome the reader will build, it likely belongs in **Tutorial**.
+- If it exists mainly to solve an immediate operational problem, it belongs in **How-to guide**.
+
+## Cross-Linking Rules
+
+Quadrants should cooperate rather than compete. Each document should point to adjacent documentation types when a different reader need appears.
+
+| From | Cross-link pattern |
+|------|--------------------|
+| Tutorial | `For the full API, see [Reference].` |
+| How-to guide | `To understand why, see [Explanation].` |
+| Reference | `For a guide on using this, see [How-to].` |
+| Explanation | `To get started, see [Tutorial].` |
+
+Use cross-links when content would otherwise drift into the wrong quadrant. Link instead of absorbing the adjacent material.
+
+## Attribution
+
+This document adapts concepts from the Diataxis framework at [diataxis.fr](https://diataxis.fr/), especially the quadrant descriptions and distinction pages.
+
+Source material is licensed under **CC-BY-SA 4.0**.
+
+Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).

package/scaffold/general/skills/docs/references/diataxis-quality.md

@@ -0,0 +1,76 @@
+# Diataxis Quality & Iteration
+
+How to assess and improve documentation quality using the Diátaxis framework.
+
+## Quality Checklist
+
+Run this checklist against every document created or updated during `_docs-sync`:
+
+### Quadrant Purity
+- [ ] Document serves exactly ONE Diátaxis quadrant
+- [ ] No mixed-mode content (tutorial narration + reference tables + explanation prose)
+- [ ] Language patterns match the quadrant (see diataxis-quadrants.md)
+- [ ] If content from another quadrant is needed, it's linked — not embedded
+
+### Structure & Completeness
+- [ ] All required template sections are present (see diataxis-templates.md)
+- [ ] No empty placeholder sections
+- [ ] Cross-references to related docs in other quadrants exist
+- [ ] `type:` frontmatter tag matches the actual content quadrant
+
+### Evidence & Accuracy
+- [ ] Claims are traceable to source files, config, or AI Kit tool output
+- [ ] Unknowns are marked `[TODO]`, not guessed
+- [ ] Team-intent items are marked `[ASK USER]`
+- [ ] No stale information (version numbers, deprecated APIs, removed features)
+
+### Audience Fit
+- [ ] Tutorial: assumes beginner, teaches one skill, shows visible results at each step
+- [ ] How-To: assumes competence, addresses specific task, no unnecessary explanation
+- [ ] Reference: factual, comprehensive, consistent structure, austere
+- [ ] Explanation: provides context, takes a position, connects concepts
+
+## Iterative Improvement Process
+
+Documentation improves incrementally. Don't try to perfect everything at once.
+
+### The Loop
+
+```
+1. Pick one document (or section, or paragraph)
+2. Classify it → which Diátaxis quadrant?
+3. Check → does it serve that quadrant well? (use checklist above)
+4. Make one improvement
+5. Repeat
+```
+
+### When to Iterate
+
+| Trigger | Action |
+|---------|--------|
+| New doc created during `_docs-sync` | Run full checklist before committing |
+| Existing doc updated | Check only the modified sections |
+| Docs audit requested | Run checklist on all docs; prioritize by staleness |
+| Content feels wrong but works | Classify first — often the issue is quadrant mixing |
+
+### Organic Growth (from diataxis.fr)
+
+- Let documentation structure emerge from content needs — don't create empty four-section structures
+- A project with no tutorials doesn't need a `tutorials/` directory
+- Add documentation types as the project actually needs them
+- Perfect is the enemy of good — a correct how-to guide is better than no documentation
+
+### Scoring (optional, for audits)
+
+Per document, count how many checklist items pass out of the total applicable items.
+
+| Score | Quality | Action |
+|-------|---------|--------|
+| 100% | Excellent | No action needed |
+| 75-99% | Good | Fix during next relevant change |
+| 50-74% | Needs work | Schedule improvement |
+| <50% | Poor | Rewrite or split immediately |
+
+---
+
+*Quality framework follows the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*

package/scaffold/general/skills/docs/references/diataxis-templates.md

@@ -0,0 +1,120 @@
+# Diataxis Templates
+
+Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
+
+## Tutorial Template
+
+**Location**: `docs/guides/tutorials/{topic}.md`
+**Quadrant**: Tutorial (learning-oriented, practical)
+
+```markdown
+---
+type: tutorial
+---
+
+# Tutorial: {Title — Start with a Verb Phrase}
+
+> **What you'll build/learn**: One sentence describing the concrete outcome.
+
+## Prerequisites
+
+- {Prerequisite 1} — [install guide](link)
+- {Prerequisite 2}
+
+## Steps
+
+### 1. {First Visible Result}
+
+{Concrete action with immediate, visible output.}
+
+```bash
+{command or code}
+```
+
+> **You'll see**: {expected output — always show what success looks like}
+
+### 2. {Build on Step 1}
+
+{Next concrete action that builds on the previous result.}
+
+> **You'll see**: {expected output}
+
+### 3. {Complete the Goal}
+
+{Final action that achieves the tutorial's stated outcome.}
+
+> **You'll see**: {final result matching the "What you'll build" promise}
+
+## What You Learned
+
+{One-paragraph summary of skills acquired. No new concepts here.}
+
+## Next Steps
+
+- [How to {related task}](../guides/{topic}.md) — apply what you learned
+- [{Topic} Reference](../../reference/{topic}.md) — full API details
+- [About {concept}](../../architecture/{topic}.md) — understand the design
+```
+
+### Tutorial Rules
+
+1. **Always show results** — every step must have a "You'll see" block
+2. **Linear path only** — no branching, no optional steps, no alternatives
+3. **No explanations** — if the reader asks "why?", link to an Explanation doc
+4. **Concrete outcome** — the tutorial must produce something visible (output, file, running service)
+5. **Minimum viable scope** — teach ONE thing; link to other tutorials for more
+
+## Explanation Template
+
+**Location**: `docs/architecture/{topic}.md` or `docs/decisions/NNN-{title}.md`
+**Quadrant**: Explanation (understanding-oriented, theoretical)
+
+```markdown
+---
+type: explanation
+---
+
+# About {Topic}
+
+## Context
+
+{Why this topic matters. What problem or question it addresses. Set the stage.}
+
+## Background
+
+{Historical context, prior art, or constraints that shaped the current approach.}
+
+## How It Works
+
+{Discursive description — connections between components, data flow, design reasoning.}
+{NO step-by-step procedures — link to How-To guides for that.}
+
+## Design Decisions
+
+{Why this approach was chosen over alternatives.}
+{Link to ADRs where they exist: [ADR-NNN](../decisions/NNN-{title}.md)}
+
+## Trade-Offs
+
+| Gained | Sacrificed |
+|--------|-----------|
+| {benefit} | {cost} |
+
+## Related
+
+- [How to {task}](../guides/{topic}.md) — practical application
+- [{API} Reference](../reference/{topic}.md) — technical details
+- [Tutorial: {topic}](../guides/tutorials/{topic}.md) — hands-on introduction
+```
+
+### Explanation Rules
+
+1. **Take a position** — good explanation has perspective and opinion
+2. **Connect concepts** — show relationships, not isolated facts
+3. **No procedures** — if you write "Step 1:", move it to a How-To doc
+4. **Bounded scope** — explain ONE concept/decision/pattern per document
+5. **Link to evidence** — reference ADRs, code, or analysis tool output
+
+---
+
+*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*

package/scaffold/general/skills/docs/references/flow-artifacts-guide.md

@@ -0,0 +1,70 @@
+# Flow Artifacts Guide
+
+## What Are Flow Artifacts
+
+Flows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.
+
+Use artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.
+
+## How to Discover Artifacts
+
+```text
+flow_status()                                      # Get artifactsPath
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files
+digest({ sources: [                                # Compress into working context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Read every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.
+
+## Artifact Catalog
+
+| Artifact | Flow | Contains |
+|---|---|---|
+| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |
+| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |
+| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |
+| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |
+| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |
+| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |
+| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |
+
+## Artifact-to-Documentation Mapping
+
+| Artifact | Contains | Documentation Target | Action |
+|---|---|---|---|
+| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |
+| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |
+| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |
+| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |
+| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |
+| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |
+| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |
+| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |
+| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |
+
+## Reading Strategy
+
+Read every artifact `find()` returns. Triage by content type:
+
+| Content Signal | Documentation Value | Action |
+|---|---|---|
+| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |
+| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |
+| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |
+| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |
+
+Skip artifacts that only repeat completed work with no insights beyond the code diff.
+
+> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.
+
+## What Not to Document
+
+| Avoid | Do Instead |
+|---|---|
+| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |
+| Documenting every task or progress update | Keep only durable insights that help future readers |
+| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |

package/scaffold/general/skills/docs/references/project-knowledge-gotchas.md

@@ -0,0 +1,32 @@
+# Project Knowledge — Gotchas
+
+Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
+
+## Environment Gotchas
+
+**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
+
+**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
+
+**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
+
+**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.
+
+**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.
+
+**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.
+
+**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.
+
+**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.
+
+## Anti-Pattern Table
+
+| ❌ Don't | ✅ Do instead |
+|---------|--------------|
+| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
+| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what's actually there |
+| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |
+| Document `dist/` or `build/` naming patterns as conventions | Source files only |
+| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |
+| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |