feat(skills): deft-directive-audit — four-phase repo audit skill (Discovery, Audit, Strategy, Task Plan)
Summary
Directive has deft-directive-gh-triage for single-bug root-cause analysis, but no skill for a full-repo structured audit that produces a complete health assessment and prioritized task plan. A deft-directive-audit skill would fill this gap: it is the "brownfield health check" that users need when onboarding into an existing codebase, after a major feature push, or before a significant refactoring initiative.
The four-phase structure
Based on a widely-bookmarked repo audit prompt (2,419 bookmarks, June 9 2026):
Phase 1 / Discovery and Mapping (read before judging)
Map directory structure, identify entry points, read manifests/lockfiles/CI config/docs, determine project purpose and maturity, note existing conventions. Output: a Repo Map with architecture sketch and anything surprising.
Phase 2 / Audit (evidence-based, severity-rated)
Audit eight dimensions, each finding labeled Fact or Judgment (file:line required for facts) with severity Critical/High/Medium/Low:
- Architecture and design
- Code quality
- Security
- Testing
- Performance
- Dependencies
- DevEx and operations
- Documentation
Rules: prefer 15 high-confidence findings over 50 speculative ones. Also list strengths. Output: Audit Report grouped by dimension and sorted by severity.
Phase 3 / Improvement Strategy
Identify 3-5 themes explaining most findings. For each: target state, principle, explicit trade-offs (what NOT to fix and why), and measurable definition of done.
Phase 4 / Detailed Task Plan
Break strategy into tasks, each with: title+description, files affected, acceptance criteria, effort estimate (S/M/L/XL per issue #1581), change risk, and dependencies. Order into milestones:
Final output: Executive Summary (health grade A-F, top 3 risks, top 3 opportunities), Repo Map, Audit Report, Improvement Strategy, Task Plan, Open Questions.
How it fits directive
This skill composes existing directive tools:
- Phase 1 maps to the existing map strategy
- Phase 2 findings feed deft-directive-gh-triage for individual issues
- Phase 3 strategy feeds deft-directive-refinement for backlog creation
- Phase 4 task plan produces scope vBRIEFs for vbrief/proposed/
The audit skill is the front-door for brownfield adoption (docs/BROWNFIELD.md) and for periodic health checks on established projects.
Proposed files
- skills/deft-directive-audit/SKILL.md -- four-phase workflow
- skills/deft-directive-audit/REFERENCE.md -- eight-dimension audit checklist with examples per dimension
- .agents/skills/deft-directive-audit/SKILL.md -- stub
Acceptance criteria
Related
Source
@meta_alchemist repo audit prompt (https://x.com/meta_alchemist/status/2064431279383433646, 2,419 bookmarks, June 9 2026). Full four-phase structure with eight audit dimensions, severity rating, milestone structure, effort estimates, strengths section, and explicit what-not-to-fix constraint.
feat(skills): deft-directive-audit — four-phase repo audit skill (Discovery, Audit, Strategy, Task Plan)
Summary
Directive has deft-directive-gh-triage for single-bug root-cause analysis, but no skill for a full-repo structured audit that produces a complete health assessment and prioritized task plan. A deft-directive-audit skill would fill this gap: it is the "brownfield health check" that users need when onboarding into an existing codebase, after a major feature push, or before a significant refactoring initiative.
The four-phase structure
Based on a widely-bookmarked repo audit prompt (2,419 bookmarks, June 9 2026):
Phase 1 / Discovery and Mapping (read before judging)
Map directory structure, identify entry points, read manifests/lockfiles/CI config/docs, determine project purpose and maturity, note existing conventions. Output: a Repo Map with architecture sketch and anything surprising.
Phase 2 / Audit (evidence-based, severity-rated)
Audit eight dimensions, each finding labeled Fact or Judgment (file:line required for facts) with severity Critical/High/Medium/Low:
Rules: prefer 15 high-confidence findings over 50 speculative ones. Also list strengths. Output: Audit Report grouped by dimension and sorted by severity.
Phase 3 / Improvement Strategy
Identify 3-5 themes explaining most findings. For each: target state, principle, explicit trade-offs (what NOT to fix and why), and measurable definition of done.
Phase 4 / Detailed Task Plan
Break strategy into tasks, each with: title+description, files affected, acceptance criteria, effort estimate (S/M/L/XL per issue #1581), change risk, and dependencies. Order into milestones:
Flag quick wins (high impact, S effort) separately.
Final output: Executive Summary (health grade A-F, top 3 risks, top 3 opportunities), Repo Map, Audit Report, Improvement Strategy, Task Plan, Open Questions.
How it fits directive
This skill composes existing directive tools:
The audit skill is the front-door for brownfield adoption (docs/BROWNFIELD.md) and for periodic health checks on established projects.
Proposed files
Acceptance criteria
Related
Source
@meta_alchemist repo audit prompt (https://x.com/meta_alchemist/status/2064431279383433646, 2,419 bookmarks, June 9 2026). Full four-phase structure with eight audit dimensions, severity rating, milestone structure, effort estimates, strengths section, and explicit what-not-to-fix constraint.