Back to Details

audit-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

audit-context

audit-context

Diagnose a nao context. Find gaps, MECE violations, failure root causes, and bloat. Output is a short in-conversation report ending in a prioritized plan. Diagnose only — never fix. Route fixes to 
write-context-rules
/ 
add-semantic-layer
/ 
create-context-tests
.
Run any time: right after 
setup-context
, mid-build, before a release, or when the agent's behavior gets surprising.
诊断nao context。找出缺口、MECE违规问题、失败根源以及冗余内容。输出为简短的对话式报告，结尾附上优先级计划。仅诊断——绝不修复。修复操作请转至
write-context-rules
/ 
add-semantic-layer
/ 
create-context-tests
。
可在任意时间运行：
setup-context
完成后、构建过程中、发布前，或当Agent行为出现异常时。

Six checks (run in order)

六项检查（按顺序执行）

1. Synced context

1. 已同步上下文

Read 
nao_config.yaml
. What's wired in (warehouse, repos, Notion, semantic layer, MCPs)? What's missing (dbt repo, ETL configs, BI repo, internal docs)? Has 
nao sync
run — are 
databases/
, 
repos/
, 
docs/
, 
semantics/
populated?
Scope check: <100 tables is the hard ceiling, ≤20 is the target. Better 12 well-documented tables than 80 half-documented ones. Flag oversized scope explicitly — it's the biggest predictor of reliability failure.
读取
nao_config.yaml
。已接入哪些组件（数据仓库、代码库、Notion、语义层、MCPs）？缺少哪些（dbt代码库、ETL配置、BI代码库、内部文档）？是否运行过
nao sync
——
databases/
、
repos/
、
docs/
、
semantics/
目录是否已填充？
范围检查：少于100张表是硬性上限，≤20张是目标。12张文档完善的表比80张半文档化的表更好。需明确标记超出范围的情况——这是可靠性失败的最大预测因素。

2. 
RULES.md
vs target structure

2. 
RULES.md
与目标结构对比

Six standard sections (from 
write-context-rules
): Business overview, Data architecture, Core data models (Most Used + Tables detail), Key Metrics Reference, Date filtering, Analysis Process. Per section, mark present / missing / thin. Flag placeholders, 
TODO:
markers, and metric entries with no source-of-truth pointer.
write-context-rules
定义的六个标准章节：业务概述、数据架构、核心数据模型（最常用表+表格详情）、关键指标参考、日期过滤、分析流程。针对每个章节，标记存在/缺失/内容单薄。标记占位符、
TODO:
标记以及无事实来源指向的指标条目。

3. Context coverage (per table)

3. 上下文覆盖（按表统计）

For every table in 
databases/
: is it in 
## Most Used Tables
? Does it have a 
## Tables detail
block? Is there dbt context (
repos/<dbt>/models/**/schema.yml
)? Any extra 
.md
?
Then per-table gaps: undocumented columns the agent will reference, calculated fields with no explanation, foreign keys with no relation, common WHERE filters not mentioned anywhere. A table with no docs anywhere is a high-priority finding.
针对
databases/
中的每张表：是否在
## Most Used Tables
中？是否有
## Tables detail
块？是否存在dbt上下文（
repos/<dbt>/models/**/schema.yml
）？是否有额外的
.md
文档？
然后检查表级缺口：Agent会引用但未文档化的列、无解释的计算字段、无关联说明的外键、未提及的常见WHERE过滤器。完全无文档的表是高优先级发现项。

4. Data model consistency (MECE)

4. 数据模型一致性（MECE原则）

  • Mutually exclusive? Two tables computing the same metric differently (worst issue — the agent picks one unpredictably).
  • Collectively exhaustive? Asked metrics that no in-scope table can answer.
  • Duplicated columns? Same logical field under different names (
    user_id
    / 
    customer_id
    / 
    account_id
    ).
  • Ambiguous columns? 
    amount
    without unit, 
    status
    without enum values.
  • **互斥性？**两张表以不同方式计算同一指标（最严重的问题——Agent会不可预测地选择其中一个）。
  • **穷尽性？**存在无法通过范围内表格回答的指标请求。
  • **重复列？**同一逻辑字段使用不同名称（
    user_id
    / 
    customer_id
    / 
    account_id
    ）。
  • **歧义列？**无单位的
    amount
    、无枚举值的
    status
    。

5. Test coverage

5. 测试覆盖

If 
tests/
is empty → recommend 
create-context-tests
. Otherwise read 
tests/outputs/
(most recent run) and categorize each failure:
CategoryLooks likeFix
Data modelWrong column / wrong tableAdd column descriptions; clarify granularity
Date selectionWrong period / week startAdd DO/DON'T SQL in 
## Date filtering
Test issueTest SQL itself is wrongFix the test, not the context
InterpretationReasonable but different readingAdd to naming conventions or 
## Key Metrics Reference
Metric definitionWrong formula / sourceTighten 
## Key Metrics Reference
or add a semantic layer
Propose the smallest rule change per failure. Sort by impact (tests affected).
如果
tests/
目录为空→建议使用
create-context-tests
。否则读取
tests/outputs/
（最新运行结果）并对每个失败案例分类：
类别表现特征修复方案
数据模型错误列/错误表添加列描述；明确粒度
日期选择错误周期/错误周起始在
## Date filtering
中添加DO/DON'T SQL示例
测试问题测试SQL本身有误修复测试，而非上下文
解读差异合理但不同的解读添加到命名约定或
## Key Metrics Reference
中
指标定义错误公式/错误来源细化
## Key Metrics Reference
或添加语义层
针对每个失败案例提出最小化的规则修改建议。按影响范围（受影响的测试数量）排序。

6. Token optimization

6. Token优化

  • Files >40KB (flag).
  • ## Tables detail
    blocks exceeding the 10-column cap.
  • Duplication between 
    RULES.md
    and 
    databases/<table>.md
    .
  • In-scope tables with no mention in any test or recent question (trim candidates).
  • Raw / staging tables that snuck into scope.
If 
RULES.md
is bloated, suggest moving per-table detail to 
databases/<table>.md
and keeping only the one-line pointer in 
## Most Used Tables
. For multi-domain bloat, propose a per-domain file map referenced from 
RULES.md
. Show the proposed structure before moving anything.
  • 大于40KB的文件（标记）。
  • ## Tables detail
    块超过10列上限。
  • RULES.md
    与
    databases/<table>.md
    之间的重复内容。
  • 范围内但未在任何测试或近期问题中提及的表（可考虑移除）。
  • 混入范围的原始/临时表。
如果
RULES.md
冗余，建议将表级详情移至
databases/<table>.md
，并在
## Most Used Tables
中仅保留一行指向链接。对于多领域冗余问题，建议从
RULES.md
引用按领域划分的文件映射。在移动任何内容前先展示拟议的结构。

Output (in conversation, not a file)

输出形式（对话中，而非文件）

Lead with a one-paragraph summary: sync state | scope wideness (N tables vs ≤100 ceiling) | rules quality (N/6 sections substantive) | test coverage (N tests, X% passing).
Then deep-dive only the sections with findings. Skip clean ones. Format hints:
  • Synced / RULES.md / token bloat → bulleted gaps.
  • Context coverage → table: 
    Table | RULES.md | dbt docs | Extra .md | Gap
    .
  • MECE → bullets.
  • Test failures → table: 
    Test | Category | Proposed fix
    .
End with a prioritized plan (easiest-win → biggest-work), each item naming the skill that does the work:
undefined
以一段总结开头：同步状态 | 范围宽度（N张表 vs ≤100上限） | 规则质量（6个章节中有N个内容充实） | 测试覆盖（N个测试，X%通过率）。
然后仅深入分析有发现的章节。跳过无问题的章节。格式提示：
  • 同步情况 / RULES.md / Token冗余 → 项目符号列出缺口。
  • 上下文覆盖 → 表格：
    表名 | RULES.md | dbt文档 | 额外.md | 缺口
    。
  • MECE问题 → 项目符号。
  • 测试失败 → 表格：
    测试项 | 类别 | 拟议修复方案
    。
结尾附上优先级计划（易实现→工作量大），每个条目注明执行该工作的技能：
undefined

Plan

计划

  1. (easy / 5 min) ... → write-context-rules
  2. (small / 30 min) ... → create-context-tests
  3. (medium / 1-2 hr) ... → audit-context (rerun after)
  4. (large / multi-session) ... → add-semantic-layer
undefined
  1. (简单 / 5分钟) ... → write-context-rules
  2. (小型 / 30分钟) ... → create-context-tests
  3. (中型 / 1-2小时) ... → audit-context（修复后重新运行）
  4. (大型 / 多会话) ... → add-semantic-layer
undefined

Guardrails

约束规则

  • Apply one change at a time. Re-run tests between fixes.
  • Tests are the source of truth. If the user says "it's working," ask for the latest pass rate first.
  • Don't move or split files without confirmation. Show the file map first.
  • Don't fix in this skill — diagnose only.
  • 一次仅应用一项更改。修复之间重新运行测试。
  • 测试是事实来源。如果用户说“运行正常”，先询问最新通过率。
  • 未经确认请勿移动或拆分文件。先展示文件映射。
  • 本技能仅诊断，不修复。