candid-init_skill

Overview

This skill generates a project-specific Technical.md and a .candid/config.json by performing a deep, evidence-driven audit of a TypeScript codebase. It reads directory structure, import graphs, and representative source files to produce actionable architecture decisions, pattern documentation, and gap analysis. The output is written as if a senior technical architect spent days inside the repository, citing real files and lines where relevant.

How this skill works

Run the skill in the repo root and it first checks for existing .candid/Technical.md and config.json to avoid accidental overwrite. It detects effort level (quick, medium, thorough), framework (React, Node, minimal), and existing tooling (linters, tsconfig) and then executes parallel analysis agents to read files, infer layers, naming, error handling, tests, and framework patterns. Finally it synthesizes prioritized rules and examples into a Technical.md and emits a machine-readable config.json to drive repeatable audits.

When to use it

• Before a major refactor to codify architecture constraints and edge cases.
• Onboarding new engineers to provide an evidence-backed code map and conventions.
• To generate baseline architecture documentation when none exists.
• As part of a security or QA pass to highlight error‑handling and validation gaps.
• When preparing a mono-repo for packaging, extraction of services, or split.

Best practices

• Run in thorough mode for a complete, prioritized rule set; use medium for faster but still meaningful output.
• Let the skill skip rules covered by existing linters — focus the Technical.md on architecture and domain rules linters can't enforce.
• Keep the generated .candid/config.json under source control to standardize future audits and automated checks.
• Review and approve proposed rules before applying automated fixes; the tool cites file paths and examples for quick verification.
• Use generated rules as gating checks in CI (e.g., enforce layer boundaries, banned-cross-imports) rather than blind auto-fixes.

Example use cases

• Generate a Technical.md that lists detected layers (controllers, services, repositories) with concrete path examples and violations found.
• Create a config.json that encodes allowed import directions (e.g., controllers → services, services → repositories) for CI enforcement.
• Produce a naming & style section with extracted examples (component names, hook prefixes, boolean naming) and suggested canonical rules.
• Identify error-handling gaps: missing centralized error middleware, inconsistent error shape, or uncaught promise rejections with file references.
• Map test coverage by directory and list high-impact areas missing tests with suggested test patterns and sample test file references.