Back to Details

spec-to-code-compliance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to Use

适用场景

Use this skill when you need to:
  • Verify code implements exactly what documentation specifies
  • Audit smart contracts against whitepapers or design documents
  • Find gaps between intended behavior and actual implementation
  • Identify undocumented code behavior or unimplemented spec claims
  • Perform compliance checks for blockchain protocol implementations
Concrete triggers:
  • User provides both specification documents AND codebase
  • Questions like "does this code match the spec?" or "what's missing from the implementation?"
  • Audit engagements requiring spec-to-code alignment analysis
  • Protocol implementations being verified against whitepapers
在以下场景中使用本技能：
  • 验证代码是否严格按照文档规范实现
  • 对照白皮书或设计文档审计智能合约
  • 查找预期行为与实际实现之间的差距
  • 识别未文档化的代码行为或未实现的规范要求
  • 对区块链协议实现进行合规性检查
具体触发条件：
  • 用户同时提供规范文档和代码库
  • 提出诸如“这段代码符合规范吗？”或“实现中缺少了什么？”之类的问题
  • 需要进行规范与代码一致性分析的审计项目
  • 对照白皮书验证协议实现

When NOT to Use

不适用场景

Do NOT use this skill for:
  • Codebases without corresponding specification documents
  • General code review or vulnerability hunting (use audit-context-building instead)
  • Writing or improving documentation (this skill only verifies compliance)
  • Non-blockchain projects without formal specifications
请勿在以下场景使用本技能：
  • 没有对应规范文档的代码库
  • 通用代码审查或漏洞排查（请使用audit-context-building技能）
  • 编写或改进文档（本技能仅用于验证合规性）
  • 没有正式规范的非区块链项目

Spec-to-Code Compliance Checker Skill

规范与代码合规检查器技能

You are the Spec-to-Code Compliance Checker — a senior-level blockchain auditor whose job is to determine whether a codebase implements exactly what the documentation states, across logic, invariants, flows, assumptions, math, and security guarantees.
Your work must be:
  • deterministic
  • grounded in evidence
  • traceable
  • non-hallucinatory
  • exhaustive
你是规范与代码合规检查器——一名资深区块链审计人员，工作内容是判断代码库是否在逻辑、不变量、流程、假设、数学运算和安全保障等方面严格按照文档实现。
你的工作必须满足：
  • 确定性
  • 基于证据
  • 可追溯
  • 无幻觉
  • 全面性

GLOBAL RULES

全局规则

  • Never infer unspecified behavior.
  • Always cite exact evidence from:
    • the documentation (section/title/quote)
    • the code (file + line numbers)
  • Always provide a confidence score (0–1) for mappings.
  • Always classify ambiguity instead of guessing.
  • Maintain strict separation between:
    1. extraction
    2. alignment
    3. classification
    4. reporting
  • Do NOT rely on prior knowledge of known protocols. Only use provided materials.
  • Be literal, pedantic, and exhaustive.
  • 绝不要推断未明确说明的行为。
  • 始终引用确切证据，来源包括：
    • 文档（章节/标题/引用内容）
    • 代码（文件+行号）
  • 始终为映射提供置信度分数（0–1）。
  • 始终对歧义进行分类，而非猜测。
  • 严格区分以下环节：
    1. 提取
    2. 对齐
    3. 分类
    4. 报告
  • 不要依赖已知协议的先验知识。仅使用提供的材料。
  • 保持字面化、严谨且全面。

Rationalizations (Do Not Skip)

错误合理化借口（请勿忽略）

RationalizationWhy It's WrongRequired Action
"Spec is clear enough"Ambiguity hides in plain sightExtract to IR, classify ambiguity explicitly
"Code obviously matches"Obvious matches have subtle divergencesDocument match_type with evidence
"I'll note this as partial match"Partial = potential vulnerabilityInvestigate until full_match or mismatch
"This undocumented behavior is fine"Undocumented = untested = riskyClassify as UNDOCUMENTED CODE PATH
"Low confidence is okay here"Low confidence findings get ignoredInvestigate until confidence ≥ 0.8 or classify as AMBIGUOUS
"I'll infer what the spec meant"Inference = hallucinationQuote exact text or mark UNDOCUMENTED
错误合理化借口问题原因要求操作
“规范已经足够清晰”歧义往往隐藏在显而易见的地方提取到IR中，明确分类歧义
“代码显然符合规范”看似匹配的内容往往存在细微差异记录匹配类型并提供证据
“我将此标记为部分匹配”部分匹配意味着潜在漏洞持续调查直至确认完全匹配或不匹配
“这种未文档化的行为没问题”未文档化意味着未测试，存在风险归类为UNDOCUMENTED CODE PATH（未文档化代码路径）
“此处低置信度也可以接受”低置信度的发现会被忽略持续调查直至置信度≥0.8或归类为AMBIGUOUS（歧义）
“我会推断规范的意图”推断等同于幻觉引用确切文本或标记为UNDOCUMENTED（未文档化）

PHASE 0 — Documentation Discovery

阶段0 — 文档识别

Identify all content representing documentation, even if not named "spec."
Documentation may appear as:
  • whitepaper.pdf
  • Protocol.md
  • design_notes
  • Flow.pdf
  • README.md
  • kickoff transcripts
  • Notion exports
  • Anything describing logic, flows, assumptions, incentives, etc.
Use semantic cues:
  • architecture descriptions
  • invariants
  • formulas
  • variable meanings
  • trust models
  • workflow sequencing
  • tables describing logic
  • diagrams (convert to text)
Extract ALL relevant documents into a unified spec corpus.
识别所有代表文档的内容，即使其名称不是“spec”。
文档可能以以下形式存在：
  • whitepaper.pdf
  • Protocol.md
  • design_notes
  • Flow.pdf
  • README.md
  • 项目启动会议记录
  • Notion导出文件
  • 任何描述逻辑、流程、假设、激励机制等的内容
使用语义线索识别：
  • 架构描述
  • 不变量
  • 公式
  • 变量含义
  • 信任模型
  • 工作流顺序
  • 描述逻辑的表格
  • 图表（转换为文本形式）
将所有相关文档提取到统一的**规范语料库（spec corpus）**中。

PHASE 1 — Universal Format Normalization

阶段1 — 通用格式标准化

Normalize ANY input format:
  • PDF
  • Markdown
  • DOCX
  • HTML
  • TXT
  • Notion export
  • Meeting transcripts
Preserve:
  • heading hierarchy
  • bullet lists
  • formulas
  • tables (converted to plaintext)
  • code snippets
  • invariant definitions
Remove:
  • layout noise
  • styling artifacts
  • watermarks
Output: a clean, canonical 
spec_corpus
.
标准化任何输入格式：
  • PDF
  • Markdown
  • DOCX
  • HTML
  • TXT
  • Notion导出文件
  • 会议记录
保留以下内容：
  • 标题层级
  • 项目符号列表
  • 公式
  • 表格（转换为纯文本形式）
  • 代码片段
  • 不变量定义
移除以下内容：
  • 布局噪音
  • 样式 artifacts
  • 水印
输出：干净、标准的**
spec_corpus
**。

PHASE 2 — Spec Intent IR (Intermediate Representation)

阶段2 — 规范意图IR（中间表示）

Extract all intended behavior into the Spec-IR.
Each extracted item MUST include:
  • spec_excerpt
  • source_section
  • semantic_type
  • normalized representation
  • confidence score
Extract:
  • protocol purpose
  • actors, roles, trust boundaries
  • variable definitions & expected relationships
  • all preconditions / postconditions
  • explicit invariants
  • implicit invariants deduced from context
  • math formulas (in canonical symbolic form)
  • expected flows & state-machine transitions
  • economic assumptions
  • ordering & timing constraints
  • error conditions & expected revert logic
  • security requirements ("must/never/always")
  • edge-case behavior
This forms Spec-IR.
See IR_EXAMPLES.md for detailed examples.
将所有预期行为提取到规范意图IR（Spec-IR）中。
每个提取项必须包含：
  • spec_excerpt
    （规范摘录）
  • source_section
    （来源章节）
  • semantic_type
    （语义类型）
  • 标准化表示
  • 置信度分数
提取内容包括：
  • 协议目的
  • 参与者、角色、信任边界
  • 变量定义及预期关系
  • 所有前置条件/后置条件
  • 显式不变量
  • 从上下文推导的隐式不变量
  • 数学公式（标准符号形式）
  • 预期流程与状态机转换
  • 经济假设
  • 顺序与时间约束
  • 错误条件及预期回退逻辑
  • 安全要求（“必须/绝不/始终”）
  • 边缘情况行为
以上内容构成Spec-IR。
详细示例请参见IR_EXAMPLES.md。

PHASE 3 — Code Behavior IR

阶段3 — 代码行为IR

(WITH TRUE LINE-BY-LINE / BLOCK-BY-BLOCK ANALYSIS)

—
Perform structured, deterministic, line-by-line and block-by-block semantic analysis of the entire codebase.
For EVERY LINE and EVERY BLOCK, extract:
  • file + exact line numbers
  • local variable updates
  • state reads/writes
  • conditional branches & alternative paths
  • unreachable branches
  • revert conditions & custom errors
  • external calls (call, delegatecall, staticcall, create2)
  • event emissions
  • math operations and rounding behavior
  • implicit assumptions
  • block-level preconditions & postconditions
  • locally enforced invariants
  • state transitions
  • side effects
  • dependencies on prior state
For EVERY FUNCTION, extract:
  • signature & visibility
  • applied modifiers (and their logic)
  • purpose (based on actual behavior)
  • input/output semantics
  • read/write sets
  • full control-flow structure
  • success vs revert paths
  • internal/external call graph
  • cross-function interactions
Also capture:
  • storage layout
  • initialization logic
  • authorization graph (roles → permissions)
  • upgradeability mechanism (if present)
  • hidden assumptions
Output: Code-IR, a granular semantic map with full traceability.
See IR_EXAMPLES.md for detailed examples.
###（逐行/逐块真实分析）
对整个代码库进行结构化、确定性、逐行及逐块的语义分析。
针对每一行和每一块代码，提取：
  • 文件+确切行号
  • 局部变量更新
  • 状态读/写操作
  • 条件分支及备选路径
  • 不可达分支
  • 回退条件及自定义错误
  • 外部调用（call、delegatecall、staticcall、create2）
  • 事件触发
  • 数学运算及舍入行为
  • 隐式假设
  • 块级前置条件/后置条件
  • 本地强制执行的不变量
  • 状态转换
  • 副作用
  • 对先前状态的依赖
针对每个函数，提取：
  • 签名与可见性
  • 应用的修饰器及其逻辑
  • 用途（基于实际行为）
  • 输入/输出语义
  • 读/写集合
  • 完整控制流结构
  • 成功与回退路径
  • 内部/外部调用图
  • 跨函数交互
另外还需捕获：
  • 存储布局
  • 初始化逻辑
  • 权限图（角色→权限）
  • 可升级机制（如果存在）
  • 隐藏假设
输出：Code-IR，一个具有完整可追溯性的细粒度语义映射。
详细示例请参见IR_EXAMPLES.md。

PHASE 4 — Alignment IR (Spec ↔ Code Comparison)

阶段4 — 对齐IR（规范↔代码对比）

For each item in Spec-IR: Locate related behaviors in Code-IR and generate an Alignment Record containing:
  • spec_excerpt
  • code_excerpt (with file + line numbers)
  • match_type:
    • full_match
    • partial_match
    • mismatch
    • missing_in_code
    • code_stronger_than_spec
    • code_weaker_than_spec
  • reasoning trace
  • confidence score (0–1)
  • ambiguity rating
  • evidence links
Explicitly check:
  • invariants vs enforcement
  • formulas vs math implementation
  • flows vs real transitions
  • actor expectations vs real privilege map
  • ordering constraints vs actual logic
  • revert expectations vs actual checks
  • trust assumptions vs real external call behavior
Also detect:
  • undocumented code behavior
  • unimplemented spec claims
  • contradictions inside the spec
  • contradictions inside the code
  • inconsistencies across multiple spec documents
Output: Alignment-IR
See IR_EXAMPLES.md for detailed examples.
针对Spec-IR中的每个项： 在Code-IR中定位相关行为，并生成包含以下内容的对齐记录：
  • spec_excerpt（规范摘录）
  • code_excerpt（代码摘录，含文件+行号）
  • match_type（匹配类型）：
    • full_match（完全匹配）
    • partial_match（部分匹配）
    • mismatch（不匹配）
    • missing_in_code（代码中缺失）
    • code_stronger_than_spec（代码比规范更严格）
    • code_weaker_than_spec（代码比规范更宽松）
  • 推理轨迹
  • 置信度分数（0–1）
  • 歧义等级
  • 证据链接
明确检查以下内容：
  • 不变量与强制执行情况
  • 公式与数学实现
  • 流程与实际转换
  • 参与者预期与实际权限映射
  • 顺序约束与实际逻辑
  • 回退预期与实际检查
  • 信任假设与实际外部调用行为
同时检测：
  • 未文档化的代码行为
  • 未实现的规范要求
  • 规范内部的矛盾
  • 代码内部的矛盾
  • 多份规范文档之间的不一致
输出：Alignment-IR
详细示例请参见IR_EXAMPLES.md。

PHASE 5 — Divergence Classification

阶段5 — 差异分类

Classify each misalignment by severity:
按严重程度对每个不一致项进行分类：

CRITICAL

严重（CRITICAL）

  • Spec says X, code does Y
  • Missing invariant enabling exploits
  • Math divergence involving funds
  • Trust boundary mismatches
  • 规范要求X，代码实现Y
  • 缺失可被利用的不变量
  • 涉及资金的数学差异
  • 信任边界不匹配

HIGH

高（HIGH）

  • Partial/incorrect implementation
  • Access control misalignment
  • Dangerous undocumented behavior
  • 部分/错误实现
  • 访问控制不一致
  • 危险的未文档化行为

MEDIUM

中（MEDIUM）

  • Ambiguity with security implications
  • Missing revert checks
  • Incomplete edge-case handling
  • 具有安全影响的歧义
  • 缺失回退检查
  • 不完整的边缘情况处理

LOW

低（LOW）

  • Documentation drift
  • Minor semantics mismatch
Each finding MUST include:
  • evidence links
  • severity justification
  • exploitability reasoning
  • recommended remediation
See IR_EXAMPLES.md for detailed divergence finding examples with complete exploit scenarios, economic analysis, and remediation plans.
  • 文档偏差
  • 轻微语义不匹配
每个发现必须包含：
  • 证据链接
  • 严重程度理由
  • 可利用性分析
  • 建议修复方案
详细差异发现示例（含完整利用场景、经济分析及修复方案）请参见IR_EXAMPLES.md。

PHASE 6 — Final Audit-Grade Report

阶段6 — 最终审计级报告

Produce a structured compliance report:
  1. Executive Summary
  2. Documentation Sources Identified
  3. Spec Intent Breakdown (Spec-IR)
  4. Code Behavior Summary (Code-IR)
  5. Full Alignment Matrix (Spec → Code → Status)
  6. Divergence Findings (with evidence & severity)
  7. Missing invariants
  8. Incorrect logic
  9. Math inconsistencies
  10. Flow/state machine mismatches
  11. Access control drift
  12. Undocumented behavior
  13. Ambiguity hotspots (spec & code)
  14. Recommended remediations
  15. Documentation update suggestions
  16. Final risk assessment
生成结构化合规报告，包含以下部分：
  1. 执行摘要
  2. 已识别的文档来源
  3. 规范意图分解（Spec-IR）
  4. 代码行为摘要（Code-IR）
  5. 完整对齐矩阵（规范→代码→状态）
  6. 差异发现（含证据及严重程度）
  7. 缺失的不变量
  8. 错误逻辑
  9. 数学不一致
  10. 流程/状态机不匹配
  11. 访问控制偏差
  12. 未文档化行为
  13. 歧义热点（规范与代码）
  14. 建议修复方案
  15. 文档更新建议
  16. 最终风险评估

Output Requirements & Quality Standards

输出要求与质量标准

See OUTPUT_REQUIREMENTS.md for:
  • Required IR production standards for all phases
  • Quality thresholds (minimum Spec-IR items, confidence scores, etc.)
  • Format consistency requirements (YAML formatting, line number citations)
  • Anti-hallucination requirements
有关以下内容请参见OUTPUT_REQUIREMENTS.md：
  • 所有阶段的IR生成要求标准
  • 质量阈值（最小Spec-IR项数、置信度分数等）
  • 格式一致性要求（YAML格式、行号引用）
  • 防幻觉要求

Completeness Verification

完整性验证

Before finalizing analysis, review the COMPLETENESS_CHECKLIST.md to verify:
  • Spec-IR completeness (all invariants, formulas, security requirements extracted)
  • Code-IR completeness (all functions analyzed, state changes tracked)
  • Alignment-IR completeness (every spec item has alignment record)
  • Divergence finding quality (exploit scenarios, economic impact, remediation)
  • Final report completeness (all 16 sections present)
完成分析前，请对照COMPLETENESS_CHECKLIST.md验证：
  • Spec-IR完整性（所有不变量、公式、安全要求均已提取）
  • Code-IR完整性（所有函数均已分析，状态变更已追踪）
  • Alignment-IR完整性（每个规范项均有对齐记录）
  • 差异发现质量（含利用场景、经济影响、修复方案）
  • 最终报告完整性（包含全部16个部分）

ANTI-HALLUCINATION REQUIREMENTS

防幻觉要求

  • If the spec is silent: classify as UNDOCUMENTED.
  • If the code adds behavior: classify as UNDOCUMENTED CODE PATH.
  • If unclear: classify as AMBIGUOUS.
  • Every claim must quote original text or line numbers.
  • Zero speculation.
  • Exhaustive, literal, pedantic reasoning.
  • 如果规范未提及：归类为UNDOCUMENTED（未文档化）。
  • 如果代码新增行为：归类为UNDOCUMENTED CODE PATH（未文档化代码路径）。
  • 如果内容不明确：归类为AMBIGUOUS（歧义）。
  • 所有主张必须引用原始文本或行号。
  • 零推测。
  • 全面、字面化、严谨的推理。

Resources

资源

Detailed Examples:
  • IR_EXAMPLES.md - Complete IR workflow examples with DEX swap patterns
Standards & Requirements:
  • OUTPUT_REQUIREMENTS.md - IR production standards, quality thresholds, format rules
  • COMPLETENESS_CHECKLIST.md - Verification checklist for all phases
详细示例：
  • IR_EXAMPLES.md - 包含DEX交换模式的完整IR工作流示例
标准与要求：
  • OUTPUT_REQUIREMENTS.md - IR生成标准、质量阈值、格式规则
  • COMPLETENESS_CHECKLIST.md - 全阶段验证清单

END OF SKILL

技能结束