| name | review-best-practice-profile |
| description | Use when the user wants to validate a practice profile before using or sharing it — e.g., "review my profile", "validate my-team.toml", "check this profile before sharing". |
| source | Grimoire project conventions; XDG Base Directory Specification (freedesktop.org) |
| tags | ["profile","review","validation","quality","contributor"] |
| related | ["write-best-practice-profile","apply-best-practice-profile","share-best-practice-profile"] |
Review Best Practice Profile
Validate a .grimoire/profiles/<name>.toml file — check format, verify skills exist, surface conflicts.
Why This Is Best Practice
Adopted by: Every package registry runs validation before publish — npm, PyPI, and Cargo all reject malformed manifests at submission time. ESLint's --print-config resolves and validates the final config before running. Grimoire profile review applies the same gate: catch issues before a profile is shared and depended on.
Impact: A profile with a broken skill name silently activates nothing for that entry — no error, no warning at runtime. Review at authoring time surfaces these before they reach team members who depend on the profile.
Why best: Review at publish time costs 30 seconds. Debugging why a profile silently skipped three skills in production costs 30 minutes. The gate is the right place.
Sources: XDG Base Directory Specification (freedesktop.org); npm publish validation; Grimoire docs/profiles.md
Steps
1. Locate the profile file
User provides name or path. Search order if only a name is given:
.grimoire/profiles/<name>.toml — project-level~/.grimoire/profiles/<name>.toml — user-level<name>.toml — current directory
If not found, report checked locations and stop.
Multi-location conflict: If the profile name matches files at more than one location (e.g., both project-level and user-level), note it before proceeding: 'Found [name].toml at [path1] (project) and [path2] (user). Reviewing [path1] — project takes precedence. To review the other, provide the full path.' Do not silently pick one without telling the user.
2. Parse TOML
If the file is malformed TOML, report the parse error with line number and stop:
✗ Parse error at line 7: expected '=' after key
3. Check required fields
| Field | Required | Check |
|---|
name | yes | non-empty string |
[[skills]] | yes | at least one entry |
skills[].name | yes | non-empty string for each entry |
description | no | warn if absent (helpful for sharing) |
4. Check each skill name
For each skills[].name, check it exists in installed grimoire skills:
- Found: mark ✓
- Not found: mark ⚠ with install hint
5. Check for skill conflicts
Read the related: frontmatter of each found skill. If two skills in the profile list each other as conflicting (or share a known-conflicting tag pairing), flag as warning. This is a soft check — conflicts are context-dependent.
Conflict detection mechanism: Two skills conflict if:
- They prescribe contradictory behavior for the same trigger (e.g., two formatting skills with opposing rules)
- One skill's tags or description explicitly contradicts another's (e.g., 'prefer immutability' vs 'prefer mutation for performance')
- The user has a pinned preference for one practice that this profile would override
For each detected conflict, show: '[skill-A] ↔ [skill-B]: [reason they conflict] — cannot apply both simultaneously.'
Example conflicts (anchors for judgment):
apply-functional-programming ↔ apply-oop-principles — mutually exclusive paradigms when applied globally to the same codebaseprefer-immutability ↔ a performance practice requiring mutation — philosophy conflict on data handlingenforce-strict-types ↔ prefer-duck-typing — type system philosophy conflict
Use these as calibration anchors when evaluating novel skill pairs.
6. Report result
Profile: my-team (4 skills)
✓ Format valid
✓ description present
✓ apply-solid-principles — found
✓ apply-domain-driven-design — found
⚠ apply-twelve-factor-app — not installed
Install: grimoire --skill engineering/architecture/apply-twelve-factor-app
✓ apply-kiss-principle — found
Result: PASS with 1 warning
Next: /share-best-practice-profile my-team
If errors exist (missing required fields, zero valid skills), result is FAIL.
FAIL is advisory, not a blocker: A FAIL result means the profile has issues worth fixing before sharing, but the user can still apply it. After showing the FAIL findings, offer: 'Fix issues before applying? [y] or apply anyway? [n]'. Never silently block application.
Common Mistakes
Skipping review before sharing. A profile that works locally (all skills installed) may fail for others if skill names are not canonical. Review against the published skill list, not just what is locally installed.
