.sinc.json File Formatv1.0

A file format convention for storing sinc-prompt structured prompts in version-controlled repositories. Validate in CI/CD, track changes over time, and enforce Nyquist completeness across your team.

The Convention

Any file with the extension .sinc.json contains exactly one sinc-prompt JSON object conforming to the sinc-prompt v1.0 JSON Schema. The file is valid JSON, human-readable, and machine-validatable.

File Structure

A .sinc.json file is a standard JSON file with the sinc-prompt structure:

// code-review.sinc.json
{
  "formula": "x(t) = Sigma x(nT) * sinc((t - nT) / T)",
  "T": "specification-axis",
  "fragments": [
    {
      "n": 0,
      "t": "PERSONA",
      "x": "You are a senior code reviewer specializing in Python backend systems."
    },
    {
      "n": 1,
      "t": "CONTEXT",
      "x": "Django 5.0 REST API serving 50,000 requests/minute. Team of 8 engineers. PR review SLA: 4 hours."
    },
    {
      "n": 2,
      "t": "DATA",
      "x": "Files changed: 12. Lines added: 340. Lines removed: 89. Test coverage before: 87.2%. Test coverage after: 84.1%."
    },
    {
      "n": 3,
      "t": "CONSTRAINTS",
      "x": "Never approve without checking error handling paths. Always verify database migration reversibility. State exact line numbers for every finding. Never suggest style changes in the same review as logic changes. Always check for N+1 query patterns in ORM calls. Never approve a coverage decrease without explicit justification. Use severity levels: BLOCKER, CRITICAL, MAJOR, MINOR. Always verify type hints match actual return values."
    },
    {
      "n": 4,
      "t": "FORMAT",
      "x": "Summary table: File | Findings | Severity. Then per-file sections with line-level comments. End with APPROVE, REQUEST_CHANGES, or NEEDS_DISCUSSION verdict."
    },
    {
      "n": 5,
      "t": "TASK",
      "x": "Review the PR diff and produce a structured code review with severity-ranked findings."
    }
  ]
}

Repository Layout

Store .sinc.json files alongside the code they relate to, or in a dedicated prompts/ directory:

# Option A: Dedicated prompts directory
project/
  prompts/
    code-review.sinc.json
    bug-triage.sinc.json
    release-notes.sinc.json
    incident-response.sinc.json
  src/
  tests/

# Option B: Co-located with code
project/
  src/
    api/
      api-review.sinc.json      # Review prompt for API changes
      handlers.py
    models/
      migration-review.sinc.json # Review prompt for model changes
      user.py

# Option C: Agent definitions
project/
  .claude/
    agents/
      surgeon.sinc.json          # Agent persona + constraints
      reviewer.sinc.json
      planner.sinc.json

Naming Convention

CI/CD Validation

Validate all .sinc.json files in your CI pipeline to enforce Nyquist completeness across your team.

GitHub Actions

# .github/workflows/sinc-validate.yml
name: Validate sinc-prompts
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
     , uses: actions/checkout@v4

     , name: Install sinc-llm
        run: pip install sinc-llm

     , name: Validate all .sinc.json files
        run: |
          EXIT_CODE=0
          for file in $(find . -name "*.sinc.json" -type f); do
            echo "Validating: $file"
            if ! sinc-llm validate "$file"; then
              EXIT_CODE=1
            fi
          done
          exit $EXIT_CODE

     , name: Check SNR thresholds
        run: |
          for file in $(find . -name "*.sinc.json" -type f); do
            SNR=$(sinc-llm snr "$file" --quiet)
            echo "$file: SNR=$SNR"
            if (( $(echo "$SNR < 0.65" | bc -l) )); then
              echo "FAIL: $file has SNR $SNR (minimum: 0.65)"
              exit 1
            fi
          done

Pre-commit Hook

# .pre-commit-config.yaml
repos:
 , repo: local
    hooks:
     , id: sinc-validate
        name: Validate sinc-prompt files
        entry: sinc-llm validate
        language: system
        files: '\.sinc\.json$'
        types: [json]

Python Script

#!/usr/bin/env python3
"""CI validation script for .sinc.json files."""
import sys
import pathlib
import json
from sinc_llm import compute_snr

MIN_SNR = 0.65
errors = []

for path in pathlib.Path(".").rglob("*.sinc.json"):
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        errors.append(f"{path}: Invalid JSON, {e}")
        continue

    # Check required fields
    if "formula" not in data:
        errors.append(f"{path}: Missing 'formula' field")
    if "fragments" not in data:
        errors.append(f"{path}: Missing 'fragments' field")
        continue

    # Check all 6 bands
    bands = {f.get("n") for f in data["fragments"]}
    missing = {0,1,2,3,4,5}, bands
    if missing:
        names = {0:"PERSONA",1:"CONTEXT",2:"DATA",3:"CONSTRAINTS",4:"FORMAT",5:"TASK"}
        errors.append(f"{path}: Missing bands: {[names[n] for n in sorted(missing)]}")

    # Check SNR
    snr = compute_snr(data["fragments"])
    if snr < MIN_SNR:
        errors.append(f"{path}: SNR {snr:.4f} below minimum {MIN_SNR}")

    # Check CONSTRAINTS is longest
    by_n = {f["n"]: f for f in data["fragments"]}
    if 3 in by_n:
        c_len = len(by_n[3].get("x", ""))
        for n, f in by_n.items():
            if n != 3 and len(f.get("x", "")) > c_len:
                errors.append(
                    f"{path}: {f.get('t')} ({len(f['x'])} chars) "
                    f"longer than CONSTRAINTS ({c_len} chars)"
                )
                break

    if not errors or not any(str(path) in e for e in errors):
        print(f"  PASS  {path} (SNR: {snr:.4f})")

if errors:
    print(f"\n{len(errors)} error(s):")
    for e in errors:
        print(f"  FAIL  {e}")
    sys.exit(1)
else:
    print(f"\nAll .sinc.json files valid.")
    sys.exit(0)

Version Control Best Practices

1. Track Prompt Changes Like Code

Every .sinc.json change produces a meaningful diff. Git tracks exactly which band changed and when.

# Example git diff output:
diff --git a/prompts/code-review.sinc.json b/prompts/code-review.sinc.json
@@ -15,7 +15,7 @@
     {
       "n": 3,
       "t": "CONSTRAINTS",
-      "x": "Never approve without checking error handling."
+      "x": "Never approve without checking error handling. Always verify that new endpoints have rate limiting configured. Check for SQL injection in raw query strings."
     },

2. Use .gitattributes for Diff Quality

# .gitattributes
*.sinc.json diff=json linguist-language=JSON

3. Protect Production Prompts

# CODEOWNERS
/prompts/*.sinc.json @prompt-engineering-team
/.claude/agents/*.sinc.json @platform-team

4. Semantic Commit Messages

# Use conventional commits for prompt changes
git commit -m "feat(prompts): add incident-response sinc prompt"
git commit -m "fix(prompts): strengthen CONSTRAINTS in code-review -- add N+1 check"
git commit -m "perf(prompts): optimize code-review SNR from 0.72 to 0.83"

Schema Validation Reference

The canonical JSON Schema is published at:

Reference it in your .sinc.json files for editor autocompletion and inline validation:

{
  "$schema": "https://tokencalc.pro/schema/sinc-prompt-v1.json",
  "formula": "x(t) = Sigma x(nT) * sinc((t - nT) / T)",
  "T": "specification-axis",
  "fragments": [...]
}

VS Code will auto-validate and provide IntelliSense when the $schema field is present.

Editor Support

VS Code settings.json

{
  "json.schemas": [
    {
      "url": "https://tokencalc.pro/schema/sinc-prompt-v1.json",
      "fileMatch": ["*.sinc.json"]
    }
  ]
}

Resources