Repository guidance

Read CLAUDE.md before editing the handbook. It defines the corpus structure, editorial rules, frontmatter contract, and required verification commands.

Knowledge-base conversations

Follow the knowledge conversation principle whenever the user discusses a topic, design choice, or learning question with this knowledge base. Apply this in the current conversation as well as future repository sessions.

The user should not have to know a prerequisite exists before the assistant explains it. Answer the immediate question, then actively look for relevant missing foundations, incomplete coverage, disconnected concepts, and outdated or conflicting guidance. Explain the most consequential gaps and organize them into concepts, relationships, decisions, and evaluation criteria. Do this without waiting for an explicit gap-audit request.

Support coverage claims with inspected files and search scope. A retrieval miss is not proof of absence. Separate corpus evidence, verified external research, and your own inferences; never present inferred prerequisites as facts about the user's knowledge.

Keep expansion proportional to the user's goal. Surface one to three useful gaps when warranted, rather than adding a generic checklist to every answer. Respect a request to stay narrowly focused.

When a material gap is established, create or update a concise case under docs/knowledge-cases/ within the user's authorized scope. Check for an existing case first, cite the evidence, and record the unresolved work. Case discovery does not mean the handbook has been expanded or the gap resolved.

AGENTS.md and docs/ are repository instructions and working records, outside the retrieval corpus. A separate RAG application must load the conversation principle in its assistant instructions; do not assume ordinary retrieval will enforce it.

Project qualification

When the user requests project qualification or an application-readiness assessment, default to production readiness unless they state another target. Follow the project assessment workflow and the indexed readiness contract.

Use each current handbook capability as a top-level criterion. Determine applicability and derive acceptance checks from that capability's guidance and the target project's goals; do not substitute a fixed checklist or require every capability in every application. Trace docs to code and require observed evidence where the contract calls for runtime or operational behavior. Missing evidence remains not_verified. Report failures and justified exclusions explicitly; a source-only inspection does not establish production readiness.

Use tools.project_assessment to seed the matrix and detect changes against the current KB. Keep assessments bound to the project/deployment/profile and KB snapshot. New capabilities add criteria; existing guidance changes require semantic review of their checks. Preserve old verdicts and reassess affected criteria rather than silently rewriting history.