AGENT SKILL

structural-completeness-verification

Structural Completeness Verification

License 许可
MIT
最近更新
2026-11-14
Stars
★ 18
Forks
6

01 前言 Front Matter

name
structural-completeness-verification
metadata
{ "original-index": 43, "short-description": "Structural Completeness Verification" }
description
Structural Completeness Verification

02 资源文件 1

03 SKILL.md 正文

Structural Completeness Verification

What

A systematic approach to ensuring technical documents have complete structural integrity — no orphan headers, no missing sections, no broken hierarchies, and no promised content that doesn't exist.

Why

Structural incompleteness manifests as:

  • Orphan headers: ### 4.3 Analysis with no content below
  • Missing sections: TOC promises §5 but document jumps from §4 to §6
  • Broken hierarchy: #### 2.1.1 appears under ## 3 (wrong parent)
  • Dangling references: "See Section 7" when Section 7 doesn't exist
  • Promised deliverables: "Part Three will contain..." but Part Three is empty

These defects signal incomplete work and erode reader confidence.

Structural Integrity Rules

Rule Description Violation Example
Header-content pairing Every header has content below it ### Analysis followed immediately by ### Results
Sequential numbering Sections numbered without gaps §1, §2, §4 (missing §3)
Hierarchy consistency Child sections under correct parent #### 2.1.1 under ## 3 instead of ## 2
TOC-body alignment Every TOC entry exists in body TOC shows "5. Recommendations" but §5 missing
Promise fulfillment Every "will contain" / "see below" delivers "Details below" with no details

How

Header Hierarchy Extraction

# Extract all headers with line numbers
grep -n '^#' document.md

# Expected output shows clean hierarchy:
# 10:# Title
# 25:## 1. Introduction
# 45:### 1.1 Background
# 60:### 1.2 Scope
# 80:## 2. Analysis
# ...

Structural Validation Script

const fs = require('fs');
const doc = fs.readFileSync('document.md', 'utf8');
const lines = doc.split('\n');

let issues = [];
let lastHeaderLine = -1;
let lastHeaderLevel = 0;
let lastHeaderText = '';

lines.forEach((line, i) => {
  const headerMatch = line.match(/^(#{1,6})\s+(.+)/);
  
  if (headerMatch) {
    const level = headerMatch[1].length;
    const text = headerMatch[2];
    
    // Check for empty section (header immediately followed by header)
    if (lastHeaderLine === i - 1) {
      issues.push(`Line ${lastHeaderLine + 1}: Empty section "${lastHeaderText}"`);
    }
    
    // Check for hierarchy skip (e.g., ## followed by ####)
    if (level > lastHeaderLevel + 1) {
      issues.push(`Line ${i + 1}: Hierarchy skip - "${text}" (level ${level}) under level ${lastHeaderLevel}`);
    }
    
    lastHeaderLine = i;
    lastHeaderLevel = level;
    lastHeaderText = text;
  }
});

// Check if document ends with empty section
if (lastHeaderLine === lines.length - 1 || lastHeaderLine === lines.length - 2) {
  issues.push(`Line ${lastHeaderLine + 1}: Document ends with empty section "${lastHeaderText}"`);
}

issues.forEach(issue => console.log(issue));
console.log(`\nTotal issues: ${issues.length}`);

Section Numbering Audit

# Extract section numbers
grep -oE '^#{1,4}\s+[0-9]+(\.[0-9]+)*' document.md | \
  sed 's/^#* //' | \
  sort -t. -k1,1n -k2,2n -k3,3n

# Look for:
# - Missing numbers (1, 2, 4 — where's 3?)
# - Duplicate numbers (two §2.3 sections)
# - Out-of-order numbers (3.2 before 3.1)

Promise Tracking

Search for forward references and verify they resolve:

# Find forward references
grep -n "below\|following\|next section\|will contain\|see §\|Part.*will" document.md

# For each, verify the promised content exists

Structural Completeness Checklist

## Before Publishing: Structure Audit

### Header Integrity
- [ ] No empty sections (header with no content)
- [ ] No orphan headers (### without parent ##)
- [ ] Consistent numbering scheme throughout
- [ ] No duplicate section numbers

### TOC Alignment (if TOC exists)
- [ ] Every TOC entry has matching section
- [ ] Every major section appears in TOC
- [ ] TOC page numbers / links are accurate

### Promise Fulfillment
- [ ] Every "see below" has content below
- [ ] Every "Part X will contain" has content in Part X
- [ ] Every "to be completed" is either complete or explicitly marked ⏳

### Reference Resolution
- [ ] Every §X.Y reference points to existing section
- [ ] Every "Appendix X" reference has matching appendix
- [ ] Every "Table N" reference has matching table

Common Structural Failures

Failure Cause Prevention
Empty sections Outline created, content never added Write content immediately after header
Missing sections Content deleted, header orphaned Delete header with content
Number gaps Section removed, others not renumbered Renumber after deletions
Hierarchy breaks Copy-paste from different document Adjust header levels after paste
Promise decay "Will add later" → forgotten Track promises, resolve before publish

When to Use

  • After outlining: Verify skeleton is valid before adding content
  • After major edits: Structural changes cascade
  • Before publishing: Full structural audit
  • After merging: Combined documents may have structural conflicts

Real-World Example

From the Acme Corp TDD:

Structural challenge: Inserting new §6 (366 lines) between existing §5 and Part Two.

Verification performed:

  1. New §6 has proper hierarchy: ### 6 → #### 6.1 → ##### 6.1.1
  2. No empty sections — every header has content
  3. Part Two remained "Part Two" (not renumbered to "Part Three")
  4. Charter Traceability table references §6.1–§6.6 all resolve

Result: Script confirmed all 8 deliverable rows showed valid section references, no orphan headers in new content.

Related Skills

  • 38_document_semantic_coherence.md — Structure is a coherence dimension
  • 39_cross_reference_integrity.md — References depend on structure
  • 11_gap_analysis_pattern.md — Find what's missing

04 同仓库更多 Skills

CarlosCaPe
CarlosCaPe/octorato

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 18
CarlosCaPe
CarlosCaPe/octorato

wrangler

Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workspace-skill-discovery

Discover and include ALL skills across the workspace — not just global ones. Use at the start of every session or when the user asks about available skills. Ensures project-level skills (under .claude/skills/ or skills/ in any repo) are never missed.

★ 18
CarlosCaPe
CarlosCaPe/octorato

workers-best-practices

Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

★ 18
CarlosCaPe
CarlosCaPe/octorato

winui-app

Create, build and design WinUI 3 desktop apps with C# and the Windows App SDK following Microsoft's official guidance and CommunityToolkit. Covers XAML, navigation, theming, accessibility and deployment.

★ 18
CarlosCaPe
CarlosCaPe/octorato

windows-brain-script-portability

Scripts in ~/.claude/scripts/ that run on a Windows brain: use the python3.cmd shim and not bare python3, and reconfigure stdout to UTF-8 if you print symbols. Use it when writing a brain script or triaging a Windows-only crash.

★ 18