@zigrivers/scaffold 2.28.1 → 2.38.0

package/knowledge/tools/release-management.md

@@ -0,0 +1,222 @@
+---
+name: release-management
+description: Release engineering patterns for semantic versioning and changelog management
+topics: [release, versioning, changelog, git]
+---
+
+# Release Management
+
+Expert knowledge for release engineering including semantic versioning, conventional commit parsing, changelog generation, quality gates, and rollback procedures.
+
+## Summary
+
+### Semantic Versioning
+
+- **Major** (`X.0.0`) — breaking changes that require consumer migration
+- **Minor** (`0.X.0`) — new features, backward-compatible additions
+- **Patch** (`0.0.X`) — bug fixes, documentation, internal refactors
+
+### Conventional Commit Parsing
+
+Parse commits since the last release to determine the version bump:
+
+- `feat:` → minor bump
+- `fix:` → patch bump
+- `BREAKING CHANGE:` footer or `!:` suffix → major bump
+- Highest-wins rule: if any commit is major, the release is major
+
+### Changelog Format
+
+Follow the [Keep a Changelog](https://keepachangelog.com/) format. Group entries by Added, Fixed, Changed, and Other. Write for users, not developers.
+
+### Quality Gates
+
+All quality gates must pass before a release. Stop if gates fail unless `--force` is explicitly used.
+
+## Deep Guidance
+
+### Semantic Versioning — Extended
+
+**Major version (breaking changes):**
+- Removing or renaming a public API endpoint, function, or command
+- Changing the behavior of an existing API in a way that breaks consumers
+- Removing configuration options or changing their meaning
+- Incompatible data format or schema changes
+
+**Minor version (new features):**
+- Adding a new API endpoint, function, or command
+- Adding new optional configuration options
+- Adding new fields to API responses (additive, non-breaking)
+- New user-facing capabilities
+
+**Patch version (fixes):**
+- Bug fixes that restore expected behavior
+- Documentation corrections
+- Internal refactors that don't affect the public API
+- Performance improvements with no API changes
+- Dependency updates (non-breaking)
+
+**Pre-release versions:**
+- `v1.2.3-rc.1` — release candidate, feature-complete but not fully tested
+- `v1.2.3-beta.1` — beta, feature-complete but may have known issues
+- `v0.x.y` — initial development, no stability guarantees
+
+### Conventional Commit Parsing — Extended
+
+**Scanning commits:**
+
+```bash
+# List commits since last tag
+git log $(git describe --tags --abbrev=0 2>/dev/null || echo "$(git rev-list --max-parents=0 HEAD)")..HEAD --oneline
+```
+
+**Determining the bump:**
+
+| Commit message | Bump |
+|---|---|
+| `feat: add export command` | minor |
+| `feat!: redesign plugin API` | major |
+| `fix: correct timezone handling` | patch |
+| `fix: resolve crash\n\nBREAKING CHANGE: config format changed` | major |
+| `chore: update dependencies` | patch |
+| `docs: update README` | patch |
+| `refactor: simplify auth flow` | patch |
+
+**Highest-wins rule:**
+If 10 commits include 8 fixes and 2 features, the release is a minor bump.
+If any single commit includes a breaking change, the release is a major bump regardless of other commits.
+
+**Edge cases:**
+- No conventional commit prefix → treat as patch
+- Multiple `feat:` commits → still a single minor bump
+- `feat:` + `BREAKING CHANGE:` → major (breaking wins)
+
+### Changelog Generation
+
+**Format (Keep a Changelog):**
+
+```markdown
+## [1.2.0] - 2026-03-29
+
+### Added
+- Export command for pipeline data (#145)
+- Bulk task creation via CSV import (#148)
+
+### Fixed
+- Timezone handling in schedule display (#146)
+- Dashboard filter state not persisting (#147)
+
+### Changed
+- Improved error messages for validation failures (#149)
+```
+
+**Writing guidelines:**
+- Audience is users, not developers — describe what changed from the user's perspective
+- Use past tense ("Added," "Fixed," "Changed")
+- Reference PR or issue numbers for traceability
+- Group by type: Added (new features), Fixed (bug fixes), Changed (modifications to existing features), Removed, Deprecated, Security
+- One line per change — keep it scannable
+- Don't include internal refactors, test additions, or CI changes unless they affect users
+
+### Quality Gates — Extended
+
+**Before releasing, verify:**
+
+1. **All tests pass** — `make check`, `make test`, or the project's equivalent
+2. **Lint clean** — no linting warnings or errors
+3. **Build succeeds** — the project compiles/bundles without errors
+4. **No uncommitted changes** — working tree is clean
+5. **On the correct branch** — releases come from `main`
+6. **Up to date with remote** — `git pull` before tagging
+
+**If gates fail:**
+- Stop the release process
+- Fix the failing gate
+- Re-run all gates from the beginning
+- Only proceed with `--force` if explicitly instructed (and document why)
+
+### GitHub Release
+
+**Creating a release:**
+
+```bash
+# Create an annotated tag
+git tag -a v1.2.0 -m "Release v1.2.0"
+
+# Push the tag
+git push origin v1.2.0
+
+# Create a GitHub release with changelog as body
+gh release create v1.2.0 --title "v1.2.0" --notes-file CHANGELOG_EXCERPT.md
+```
+
+**Pre-release versions:**
+- Use `--prerelease` flag for `v0.x` versions or release candidates
+- `gh release create v0.5.0 --prerelease --title "v0.5.0 (pre-release)"`
+
+### Rollback Procedures
+
+When a release needs to be reverted:
+
+1. **Revert the tag locally and remotely:**
+   ```bash
+   git tag -d v1.2.0
+   git push origin --delete v1.2.0
+   ```
+
+2. **Revert the commits** that were part of the bad release:
+   ```bash
+   git revert <commit-range> --no-commit
+   git commit -m "[ROLLBACK] revert v1.2.0 changes"
+   ```
+
+3. **Update version files** back to the previous version
+
+4. **Create a new patch release** with the rollback:
+   ```bash
+   git tag -a v1.1.1 -m "Rollback: revert v1.2.0"
+   git push origin v1.1.1
+   ```
+
+5. **Update the changelog** with a note explaining the rollback
+
+**Commit message convention for rollbacks:** prefix with `[ROLLBACK]` for easy identification in history.
+
+### Conditional Beads Integration
+
+When `.beads/` directory exists, enrich the changelog with task completion data:
+
+```markdown
+## [1.2.0] - 2026-03-29
+
+### Added
+- Export command for pipeline data (#145)
+
+### Completed Tasks
+- bd-42: Implement export endpoint
+- bd-43: Add export CLI command
+- bd-44: Write export integration tests
+```
+
+Cross-reference closed Beads tasks by scanning `bd close` entries since the last release tag.
+
+### Version File Detection
+
+Scan the project root for version files and update all that are found:
+
+| File | Field | Ecosystem |
+|------|-------|-----------|
+| `package.json` | `"version"` | Node.js / npm |
+| `pyproject.toml` | `[project] version` | Python |
+| `Cargo.toml` | `[package] version` | Rust |
+| `.claude-plugin/plugin.json` | `"version"` | Claude Code plugin |
+| `pubspec.yaml` | `version` | Flutter / Dart |
+| `setup.cfg` | `version` | Python (legacy) |
+| `version.txt` | entire file | Generic |
+
+After updating version files, commit them in the same commit as the changelog update, before creating the tag.
+
+## See Also
+
+- [version-strategy](./version-strategy.md) — Version file management across ecosystems
+- [git-workflow-patterns](../core/git-workflow-patterns.md) — Branching, tagging, and merge policies

package/knowledge/tools/session-analysis.md

@@ -0,0 +1,215 @@
+---
+name: session-analysis
+description: Patterns for analyzing Claude Code sessions to discover automation opportunities
+topics: [analysis, automation, sessions]
+---
+
+# Session Analysis
+
+Expert knowledge for analyzing Claude Code sessions to discover automation opportunities. Covers pattern detection, repeated action identification, and actionable automation recommendations.
+
+## Summary
+
+### Pattern Detection
+
+Review session history for recurring sequences of actions. Look for commands executed multiple times, error-retry cycles, and multi-step manual workflows that could be automated.
+
+### Repeated Action Identification
+
+Categorize repeated actions by type: git workflows, test runs, build commands, file editing patterns, environment setup, and debugging sequences.
+
+### Automation Recommendations
+
+For each discovered pattern, recommend an appropriate automation mechanism: shell aliases, git hooks, Makefile targets, Claude Code hooks, or standalone scripts. Rank by estimated time savings.
+
+## Deep Guidance
+
+### What to Look For
+
+When analyzing a session (or set of sessions), search for these signal types:
+
+**Repeated manual actions:**
+- The same command (or close variants) executed 3+ times in a session
+- Multi-step sequences performed identically each time (e.g., `git add . && git commit && git push`)
+- Copy-paste patterns between files
+
+**Common errors and their fixes:**
+- Errors that appear, are diagnosed, and fixed the same way each time
+- Lint failures that require the same remediation pattern
+- Test failures caused by environment state (not code bugs)
+
+**Workflow bottlenecks:**
+- Steps where the agent pauses to think or read documentation
+- Long command sequences that could be a single script
+- Context switches between directories or tools
+
+**Frequently-used commands:**
+- Commands with complex flags that are typed repeatedly
+- Commands that are always run together (candidates for chaining)
+
+### Pattern Categories
+
+#### Git Workflows
+
+Common automatable git patterns:
+
+| Pattern | Frequency Signal | Automation |
+|---------|-----------------|------------|
+| Branch, commit, push, create PR | Every task completion | Makefile target or script |
+| Fetch, rebase, resolve, push | Every multi-agent sync | Pre-push hook or script |
+| Clean up merged branches | End of sprint/batch | Shell alias or cron |
+| Conventional commit formatting | Every commit | Git hook (commit-msg) |
+
+#### Test Runs
+
+| Pattern | Frequency Signal | Automation |
+|---------|-----------------|------------|
+| Run specific test file during TDD | Continuous during development | Watch mode configuration |
+| Run full suite before PR | Every PR creation | Pre-push hook |
+| Re-run failed tests after fix | Error-retry cycles | Test runner watch mode |
+| Generate test coverage report | Every PR or release | CI pipeline step |
+
+#### Build Commands
+
+| Pattern | Frequency Signal | Automation |
+|---------|-----------------|------------|
+| Build before testing | Every test cycle | Makefile dependency |
+| Rebuild after dependency change | After every `npm install` / `pip install` | Post-install hook |
+| Clean build after switching branches | Every branch switch | Git post-checkout hook |
+
+#### File Editing Patterns
+
+| Pattern | Frequency Signal | Automation |
+|---------|-----------------|------------|
+| Adding boilerplate to new files | Every new file creation | File templates / generators |
+| Updating imports after adding a module | Every module creation | Auto-import tooling |
+| Adding entries to index/barrel files | Every new export | Code generator or hook |
+
+### Recommendation Types
+
+For each discovered pattern, recommend the most appropriate automation mechanism:
+
+#### Shell Aliases
+
+Best for: frequently-typed commands with complex flags.
+
+```bash
+# Example: common git log format
+alias gl="git log --oneline --graph --decorate -20"
+
+# Example: common test command
+alias mt="make test"
+```
+
+**When to recommend:** Single commands used 5+ times per session, no conditional logic needed.
+
+#### Git Hooks
+
+Best for: quality enforcement that should happen automatically at git events.
+
+| Hook | Trigger | Use Case |
+|------|---------|----------|
+| `pre-commit` | Before every commit | Lint staged files, validate frontmatter |
+| `commit-msg` | After writing commit message | Enforce conventional commit format |
+| `pre-push` | Before every push | Run test suite, check branch naming |
+| `post-checkout` | After branch switch | Reinstall dependencies, clean build artifacts |
+| `post-merge` | After merge/pull | Reinstall dependencies if lock files changed |
+
+#### Makefile Targets
+
+Best for: multi-step workflows that combine several commands.
+
+```makefile
+# Example: full release workflow
+release: check
+	@scripts/release.sh
+
+# Example: clean development reset
+reset:
+	git clean -fd
+	npm install
+	make build
+```
+
+**When to recommend:** 3+ commands always run together, may need conditional logic, team-wide usage.
+
+#### Claude Code Hooks
+
+Best for: automated behaviors tied to Claude Code events.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hook": "echo 'Running command...'"
+      }
+    ]
+  }
+}
+```
+
+**When to recommend:** Behaviors specific to AI agent workflows, context injection, automated checks during agent execution.
+
+#### Standalone Scripts
+
+Best for: complex workflows with error handling, conditional logic, and user interaction.
+
+**When to recommend:** Workflow has branching logic, needs error recovery, combines multiple tools, or is too complex for a Makefile target.
+
+### Output Format
+
+Present findings as a ranked list of automation opportunities:
+
+```
+## Automation Opportunities
+
+### 1. Branch cleanup after task completion
+- **Pattern:** Agent runs `git fetch --prune && git branch --merged ...` after every PR merge
+- **Frequency:** 4x per session
+- **Recommendation:** Add `make clean-branches` Makefile target
+- **Time savings:** ~2 min/occurrence → 8 min/session
+- **Implementation complexity:** Low (5 min to implement)
+
+### 2. Pre-PR quality check
+- **Pattern:** Agent runs `make lint && make test && git push` before every PR
+- **Frequency:** 3x per session
+- **Recommendation:** Add `make ready` target that chains lint + test + push
+- **Time savings:** ~1 min/occurrence → 3 min/session
+- **Implementation complexity:** Low (2 min to implement)
+```
+
+**Ranking criteria:**
+1. Frequency × time-per-occurrence (total time savings)
+2. Error reduction potential (automating error-prone steps)
+3. Implementation complexity (prefer quick wins)
+
+### Session History Analysis
+
+When analyzing session transcripts or tool call logs:
+
+**Tool call patterns:**
+- Count occurrences of each tool
+- Identify sequences of tool calls that always appear together
+- Flag tool calls that fail and are retried with modifications
+
+**Command patterns:**
+- Extract all Bash tool invocations
+- Group by command prefix (`git`, `make`, `npm`, etc.)
+- Identify commands with identical or near-identical arguments
+
+**Error-retry cycles:**
+- Find sequences where a command fails, the agent diagnoses, and retries
+- If the same error type appears 3+ times across sessions, it needs a preventive automation
+- Common cycle: lint fails → fix → re-lint → passes (automate the fix or add a pre-save hook)
+
+**File access patterns:**
+- Track which files are read most frequently
+- Identify files that are always read together (candidates for a combined view)
+- Flag files that are read but never modified (reference material — could be injected as context)
+
+## See Also
+
+- [dev-environment](../core/dev-environment.md) — Development environment setup
+- [claude-md-patterns](../core/claude-md-patterns.md) — CLAUDE.md configuration patterns

package/knowledge/tools/version-strategy.md

@@ -0,0 +1,200 @@
+---
+name: version-strategy
+description: Version file management across language ecosystems
+topics: [versioning, packages, ecosystems]
+---
+
+# Version Strategy
+
+Expert knowledge for detecting, updating, and synchronizing version files across language ecosystems. Covers lock file management, first-version bootstrap, mismatch detection, and dry-run workflows.
+
+## Summary
+
+### Version File Detection
+
+Scan the project root for known version files: `package.json`, `pyproject.toml`, `Cargo.toml`, `.claude-plugin/plugin.json`, `pubspec.yaml`, `setup.cfg`, `version.txt`.
+
+### Lock File Sync
+
+After updating a version file, regenerate the associated lock file to keep them in sync. Each ecosystem has its own lock file update command.
+
+### First-Version Bootstrap
+
+If no version file exists, offer to create one. Suggest `0.1.0` for new projects, `1.0.0` for stable projects with existing users.
+
+## Deep Guidance
+
+### Detection — Extended
+
+**Scan order and priority:**
+
+1. `package.json` — Node.js/npm ecosystem
+2. `pyproject.toml` — Modern Python projects (PEP 621)
+3. `Cargo.toml` — Rust projects
+4. `.claude-plugin/plugin.json` — Claude Code plugins
+5. `pubspec.yaml` — Flutter/Dart projects
+6. `setup.cfg` — Legacy Python projects
+7. `version.txt` — Generic fallback
+
+**Detection logic:**
+
+```bash
+# Find all version files in the project root
+for f in package.json pyproject.toml Cargo.toml .claude-plugin/plugin.json pubspec.yaml setup.cfg version.txt; do
+  [ -f "$f" ] && echo "Found: $f"
+done
+```
+
+A project may have multiple version files (e.g., a Claude Code plugin with both `package.json` and `.claude-plugin/plugin.json`). All detected files must be updated together.
+
+### Update Patterns Per Ecosystem
+
+#### Node.js (package.json)
+
+**Version field:** `"version": "1.2.3"` at the top level of the JSON object.
+
+**Update procedure:**
+1. Edit `package.json` to set the new version
+2. Regenerate the lock file: `npm install --package-lock-only`
+3. If `yarn.lock` exists instead: `yarn install --mode update-lockfile`
+4. Commit both `package.json` and the lock file together
+
+**Caveat:** `npm version` exists but modifies files and creates git tags automatically — prefer manual editing for more control.
+
+#### Rust (Cargo.toml)
+
+**Version field:** `version = "1.2.3"` under `[package]`.
+
+**Update procedure:**
+1. Edit `Cargo.toml` to set the new version
+2. Update the lock file: `cargo update -w` (workspace only, avoids updating all dependencies)
+3. Commit both `Cargo.toml` and `Cargo.lock` together
+
+#### Python — pyproject.toml
+
+**Version field:** `version = "1.2.3"` under `[project]`.
+
+**Update procedure:**
+1. Edit `pyproject.toml` directly
+2. No separate lock file regeneration needed (unless using `poetry` or `pip-tools`)
+3. If using Poetry: `poetry lock --no-update` after version change
+4. If using pip-tools: `pip-compile` to regenerate `requirements.txt`
+
+#### Python — setup.cfg (Legacy)
+
+**Version field:** `version = 1.2.3` under `[metadata]`.
+
+**Update procedure:**
+1. Edit `setup.cfg` directly
+2. No lock file regeneration needed
+
+#### Flutter / Dart (pubspec.yaml)
+
+**Version field:** `version: 1.2.3+4` (the `+4` is the build number).
+
+**Update procedure:**
+1. Edit `pubspec.yaml` to set the new version
+2. Run `flutter pub get` to update `pubspec.lock`
+3. Commit both files together
+
+#### Claude Code Plugin (plugin.json)
+
+**Version field:** `"version": "1.2.3"` in `.claude-plugin/plugin.json`.
+
+**Update procedure:**
+1. Edit `.claude-plugin/plugin.json` to set the new version
+2. No lock file needed
+3. Commit the file
+
+#### Generic (version.txt)
+
+**Format:** The entire file content is the version string, e.g., `1.2.3\n`.
+
+**Update procedure:**
+1. Write the new version to the file: `echo "1.2.3" > version.txt`
+2. Commit the file
+
+### First-Version Bootstrap
+
+When no version file is detected and a release is requested:
+
+1. Ask which ecosystem the project targets (or infer from existing files like `src/`, `lib/`, `Cargo.toml`, etc.)
+2. Create the appropriate version file
+3. Set the initial version:
+   - `0.1.0` for new projects under active development
+   - `1.0.0` for projects with existing users or stable APIs
+4. Commit the new version file with message: `chore: bootstrap version file at <version>`
+
+**Why 0.1.0 vs 1.0.0:**
+- `0.x.y` signals "initial development, expect breaking changes"
+- `1.0.0` signals "stable public API, semver guarantees apply"
+- Most projects should start at `0.1.0` and reach `1.0.0` when the API stabilizes
+
+### Version Mismatch Detection
+
+Before bumping, check for mismatches between the version in files and the latest git tag:
+
+```bash
+# Get version from package.json (example)
+FILE_VERSION=$(jq -r '.version' package.json)
+
+# Get latest git tag version
+TAG_VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
+
+# Compare
+if [ "$FILE_VERSION" != "$TAG_VERSION" ]; then
+  echo "Mismatch: file says $FILE_VERSION, last tag says $TAG_VERSION"
+fi
+```
+
+**When a mismatch is found:**
+
+| Scenario | Action |
+|----------|--------|
+| File version > tag version | Ask: "Release as $FILE_VERSION, or bump further?" |
+| File version < tag version | Warning: files are behind the last release — update files first |
+| File version = tag version | Normal case — bump from this version |
+| No tag exists | First release — use file version as-is or suggest a version |
+
+### Dry-Run Mode
+
+Preview all version mutations without writing to disk:
+
+```
+[DRY RUN] Would update package.json: 1.1.0 → 1.2.0
+[DRY RUN] Would update .claude-plugin/plugin.json: 1.1.0 → 1.2.0
+[DRY RUN] Would regenerate package-lock.json
+[DRY RUN] Would create git tag: v1.2.0
+[DRY RUN] Would update CHANGELOG.md with new section
+```
+
+Dry-run mode is useful for:
+- Verifying the correct version bump before committing
+- Reviewing which files would change
+- Testing the release process in CI without side effects
+
+### Multiple Version Files — Synchronization
+
+When a project has multiple version files, all must show the same version at all times.
+
+**Rules:**
+- Update all detected version files in the same commit
+- Regenerate all associated lock files in the same commit
+- Verify consistency after updating: read back each file and confirm they match
+- If a version file was missed, the pre-commit hook or CI should catch the mismatch
+
+**Example commit for a multi-file project:**
+
+```
+release: v1.2.0
+
+Updated version in:
+- package.json (1.1.0 → 1.2.0)
+- .claude-plugin/plugin.json (1.1.0 → 1.2.0)
+- package-lock.json (regenerated)
+```
+
+## See Also
+
+- [release-management](./release-management.md) — Semantic versioning rules, changelog format, quality gates
+- [git-workflow-patterns](../core/git-workflow-patterns.md) — Tagging and release workflow

package/knowledge/validation/critical-path-analysis.md

@@ -1,7 +1,7 @@
 ---
 name: critical-path-analysis
 description: Tracing critical user journeys end-to-end across all specifications
-topics: [validation, critical-path, user-journeys, end-to-end, gaps]
+topics: [validation, critical-path, user-journeys, end-to-end, gap-analysis]
 ---
 
 # Critical Path Analysis

package/knowledge/validation/cross-phase-consistency.md

@@ -8,6 +8,18 @@ topics: [validation, consistency, naming, data-flow, contracts]
 
 Cross-phase consistency validation ensures that artifacts produced across different pipeline phases agree with each other. Inconsistencies compound: a renamed entity in one phase propagates confusion into every downstream artifact. This document covers what to check, how to check it, and what findings look like.
 
+## Summary
+
+- **Naming consistency**: Trace every named concept through all artifacts; flag spelling variations, abbreviations, or synonyms for the same concept.
+- **Shared assumptions**: Verify that assumptions made in later phases (cardinality, optionality, ordering, uniqueness) are explicitly stated in earlier artifacts.
+- **Data shape consistency**: Trace entity shapes field-by-field from domain model through schema, API, and UX; verify types, naming, and format alignment.
+- **Interface contract matching**: Architecture component interfaces must match their concrete definitions in API contracts; parameter names, types, and error cases aligned.
+- **Data flow completeness**: Walk each architecture data flow step-by-step verifying source/target APIs exist and data shapes match at every boundary.
+- **Constraint propagation**: ADR constraints (technology choices, patterns, NFRs) must be reflected in all downstream artifacts.
+- **Common patterns to watch**: Enum drift, optionality mismatch, orphaned events, ghost requirements, format divergence, soft-delete vs hard-delete differences, and pagination assumption conflicts.
+
+## Deep Guidance
+
 ## Why Inconsistencies Happen
 
 Each pipeline phase is authored at a different time, possibly by different agents, with evolving understanding of the project. Common causes:

package/knowledge/validation/decision-completeness.md

@@ -1,13 +1,25 @@
 ---
 name: decision-completeness
 description: Verifying all architectural decisions are recorded, justified, and non-contradictory
-topics: [validation, decisions, adrs, completeness, contradictions]
+topics: [validation, decisions, adr, completeness, contradictions]
 ---
 
 # Decision Completeness
 
 Decision completeness validation ensures that every architectural and design decision made during the pipeline has been explicitly recorded in an ADR, that no decisions contradict each other, and that no deferred decisions remain unresolved before implementation begins.
 
+## Summary
+
+- **Explicit decision extraction**: Walk every artifact and extract every technology choice, pattern selection, and constraint trade-off as a decision requiring an ADR.
+- **Implied decision mining**: Find undocumented decisions via absence-based, convention-based, technology-stack, pattern-based, and assumption-based detection techniques.
+- **ADR coverage verification**: Every decision needs an ADR with context, rationale, alternatives, consequences, and current status.
+- **Contradiction detection**: Check cross-ADR, ADR-vs-artifact, and cross-artifact contradictions; group decisions by topic and compare for consistency.
+- **Deferred decision resolution**: Search for TBD/TODO/pending markers; all must be resolved or documented as moot before implementation.
+- **Categories checklist**: Infrastructure/platform, data, API/communication, frontend, quality, operations, and process decisions all need coverage.
+- Prioritize missing ADRs by impact: critical (architecture, data, security), major (workflow, tooling), minor (conventions, formatting).
+
+## Deep Guidance
+
 ## Why Decision Completeness Matters
 
 Unrecorded decisions become tribal knowledge. When AI agents implement the system, they have no tribal knowledge — only documented decisions. Every implicit "we agreed that..." or "obviously we'd use..." that is not in an ADR is a gap that will cause agents to guess, and guesses introduce inconsistency.