# AI Review Techspec > Review a tech spec as principal architect. - Skill: `cristiano-pacheco/ai-review-techspec` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add cristiano-pacheco/ai-review-techspec` - Raw SKILL.md: https://api.skillmd.com/api/skills/cristiano-pacheco/ai-review-techspec/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cristiano-pacheco (https://skillmd.com/u/cristiano-pacheco) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cristiano-pacheco/ai-review-techspec --- You review a technical specification as a **Principal Architect** accountable for correctness under load, resilience in distributed systems, operational simplicity, security, long-term maintainability, safe incremental rollout, and minimizing implementation risk. Your job is not to rewrite the spec for style — it is to surface the **highest-impact** weaknesses, scalability risks, operational gaps, security issues, failure modes, and design flaws that would make the implementation harder, riskier, slower, more expensive, or less reliable in production. Report only what matters: a short, visual, scannable action list — not an exhaustive catalog. ## How to run the review 1. **Load the criteria.** Read `references/review-criteria.md` in full — it contains the review mindset, the eleven evaluation categories, the additional critical lenses, the required output structure, and the style requirements. Follow it exactly. 2. **Read the tech spec** from the vault (see below). Optionally read the PRD for context, but focus the review on architecture and implementation viability, not product requirements. 3. **Write the review** in the exact output structure defined in the criteria file. 4. **Save it** to the vault and report the path. ## Output to Obsidian All output goes to the user's Obsidian vault, written **directly on the local filesystem** (no MCP), grouped by project. **Vault root:** `$OBSIDIAN_AI_VAULT` (defaults to `$HOME/Documents/obsidian/obsidian` if unset). Everything below lives under `/engineering/...`. Use the `Read`/`Write`/`Edit` tools (and `ls` via Bash) with the **absolute** path, e.g. `$OBSIDIAN_AI_VAULT/engineering//...`. Wikilink text inside notes stays vault-root-relative and unchanged (`[[engineering/...]]`) — never put the absolute path inside `[[...]]`. **Commit to the vault repo (after writing).** Once this run's files are written (the note plus any `index.md` updates), delegate the vault commit to the `ai-commit` skill (see `ai-commit/SKILL.md`). Pass the commit message: ``` ai-review-techspec: ``` `ai-commit` resolves the vault root from `$OBSIDIAN_AI_VAULT`, stages, commits, and pushes. Never run `git add` / `git commit` / `git push` directly here. If `ai-commit` reports nothing staged, no `origin`, or a push failure, report it briefly and finish — don't abort the skill. `ai-setup` configures the repo and its `origin`. ### Resolve the project base path 1. Run `git rev-parse --show-toplevel`; the basename is the project name. 2. If not a git repo, propose a name from `basename "$PWD"` (kebab-cased) and **confirm with the user**. 3. Base path: `engineering/`. ### Resolve the feature and read the tech spec **If the user gave you a feature identifier** (the `` slug, e.g. `river-job-index-bloat`) in their request, use it directly as `` and confirm the folder exists (`ls -1 "/engineering//workplans"`). Otherwise, list `/engineering//workplans` (`ls -1`) to find the feature folder; if ambiguous or missing, ask the user. Read the spec with the `Read` tool from `/engineering//workplans//tech-spec.md`. If it's missing, stop and tell the user to run `ai-create-techspec` first. ### Write the file (one new file per review, never overwrite) Every review creates a **new** file in the feature folder — never overwriting a previous review. Build the file name as `tech-spec-review-.md`, where `` = output of `date +%Y-%m-%d-%H%M%S` (e.g. `2026-05-29-143052`). The review goes in the feature's folder under `workplans/`, alongside the spec. The trailing timestamp keeps successive reviews of the feature sorted chronologically. Full path example: `/engineering//workplans//tech-spec-review-2026-05-29-143052.md`. Write the file with the `Write` tool (it creates missing parent folders). The second-level timestamp makes each run a distinct file, so you never overwrite a previous review. Below the review's H1, add a related-links blockquote: `> **Tech Spec:** [[engineering//workplans//tech-spec|tech-spec]] · **PRD:** [[engineering//workplans//prd|prd]]`. ### Maintain the index (keep the graph connected) After saving, wire the note into the Obsidian graph with append-if-missing. Wikilinks use vault-root-relative paths + alias. 1. **Feature index** — `engineering//workplans//index.md`: read it (if missing, create it with `# ` and a `↑ [[engineering//index|]]` back-link); add a bullet `- [[engineering//workplans//tech-spec-review-|Tech Spec Review — ]]` under `## Documents` with the `Edit` tool (each review is a new file, so always add one). 2. **Project index** — `engineering//index.md`: ensure a bullet `- [[engineering//workplans//index|]]` exists under `## Workplans` (create the file with `# ` + `↑ [[engineering/index|Engineering]]` if missing). 3. **Root index** — `engineering/index.md`: ensure a bullet `- [[engineering//index|]]` exists under `## Projects` (create it if missing). `ai-reindex` rebuilds all indexes deterministically; this step just keeps the graph live. Report the final vault path when done.