CtrlK
BlogDocsLog inGet started
Tessl Logo

wagneripjr/doc-this

Reverse-engineer a legacy codebase into ATDD-ready, traceable specifications

69

Quality

86%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

surface-schema.mdskills/doc-this-scout/references/

Schema — .doc-this/context/surface.json

Generated by Scout. Consumed by every downstream agent (Code Analyst, Detective, Architect, Writer, Reviewer, Data Master, Visor, Design System) for structured project context.

Full structure

{
  "generated_at": "2026-05-04T14:00:00Z",
  "project_root": "/path/to/legacy-app",
  "languages": [
    { "name": "TypeScript", "extensions": [".ts", ".tsx"], "file_count": 142 },
    { "name": "JavaScript", "extensions": [".js", ".mjs"], "file_count": 23 }
  ],
  "primary_language": "TypeScript",
  "frameworks": [
    { "name": "Next.js", "version": "14.2.0", "source": "package.json" },
    { "name": "Prisma", "version": "5.10.0", "source": "package.json" }
  ],
  "package_manager": "pnpm",
  "entry_points": [
    { "path": "src/app/layout.tsx", "type": "app_entry" },
    { "path": "src/server.ts", "type": "server_entry" }
  ],
  "config_files": [
    "next.config.js", ".env.example", "tsconfig.json"
  ],
  "ci_cd": [
    ".github/workflows/deploy.yml",
    ".github/workflows/ci.yml"
  ],
  "containers": {
    "dockerfile": "Dockerfile",
    "compose": "docker-compose.yml",
    "kubernetes": null
  },
  "database_hints": [
    { "path": "prisma/schema.prisma", "type": "prisma_schema" },
    { "path": "prisma/migrations/", "type": "migrations_dir" }
  ],
  "test_framework": "Vitest",
  "test_file_count": 47,
  "e2e_framework": "Playwright",
  "modules": [
    "auth", "orders", "payments", "users", "notifications"
  ],
  "total_files": 312,
  "organization_suggestion": {
    "granularity": "module",
    "rationale": "Top-level folders are organized by domain: auth/, orders/, payments/, users/, notifications/.",
    "signals": [
      { "type": "top_level_domain_folders", "evidence": ["src/auth/", "src/orders/", "src/payments/"] }
    ],
    "features": []
  }
}

Required fields

generated_at, languages, primary_language, frameworks, entry_points, modules, organization_suggestion

Optional fields

Everything else — include only what's actually found.

organization_suggestion

Suggestion for how to organize generated specs. Read by Doc-This to pre-mark the default option in the specs-organization menu.

Subfields

FieldTypeRequiredDescription
granularitystringyesOne of: module, use-case, endpoint, hybrid, feature, custom. Scout never suggests custom — that comes only from user choice.
rationalestringyesShort sentence explaining the suggestion. Shown in the menu as "Reason:".
signalsarrayyesDetected signals leading to the suggestion. Each item has type and evidence (list of relative paths). May be empty when fallback feature is used.
featuresarrayyes when granularity = "feature"Discovered feature names. Each becomes a first-level folder.

Heuristics for granularity

Detected signalSuggested granularity
Centralized routing (routes.*, urls.py, *Controller.cs, @RestController, OpenAPI)endpoint
Top-level domain folders (auth/, orders/, payments/)module
BDD/E2E specs (features/*.feature, BDD-style *.spec.*)use-case
Multiple signals coexisting with similar weighthybrid
No clear signalfeature (fallback; populate features with what you can extract)

Immutability

After the first run, Doc-This persists the suggested granularity to .doc-this/config.toml as scout_suggestion. On re-runs, Scout may regenerate surface.json (the legacy may have changed), but Doc-This does NOT update scout_suggestion in config.toml.

structural_extraction (optional)

Added by Scout when LSP or UA was used during surface scanning. Consumed by downstream agents to know which structural extraction source is active.

{
  "structural_extraction": {
    "source": "lsp",
    "lsp_cache_path": ".doc-this/context/lsp-cache/workspace-symbols.json"
  }
}
FieldTypeDescription
sourcestring"lsp", "ua", or "llm" — which extraction source Scout used
lsp_cache_pathstring | nullPath to cached workspace symbols (present only when source = "lsp")

Note

Use this schema as a guide. If a field doesn't apply to the project, omit it — except for the required fields listed above.

skills

doc-this-scout

references

manifest-schema.md

surface-schema.md

SKILL.md

tile.json