Skip to content

/ardd-refine

Tier: core

Update a named artifact — apply new decisions, resolve open questions, handle constitution versioning; given a name that doesn't exist yet, it creates the artifact from a template (absorbs ardd-add-artifact).

Usage

/ardd-refine <name>                    # refine one artifact
/ardd-refine <name> <guidance>         # refine with inline direction
/ardd-refine                           # no-argument mode: sweep all artifacts with open questions
/ardd-refine constitution --review     # audit + propose trimming non-load-bearing principles

<name> matches a file in .project/artifacts/ (constitution, datamodel, any custom name). Naming an artifact that doesn't exist enters the create path — it's seeded from the installed template (or generic.md), registered in .project/WORKFLOW.md's Artifacts table and CLAUDE.md, and then refined normally. There is no separate add-artifact command.

No-argument mode reads .project/STATUS.md for per-artifact open-question counts and refines every artifact that has any, most-open first.

Reads

  • .project/artifacts/<name>.md (or all artifacts, in no-argument mode)
  • .project/STATUS.md — no-argument mode's work list
  • .claude/skills/ardd-artifact-templates/ — create path only

Writes

  • .project/artifacts/<name>.md — the refined artifact
  • Frontmatter, script-stamped via ardd-state.sh stamp: status (stable when substantially complete, draft when significant gaps remain), last_updated, and diagram_status: stale on renderable artifacts (unless still unrendered — nothing rendered can't go stale)
  • --review mode: when a trim is confirmed, the same constitution version-bump and Sync Impact Report writes as the normal constitution path (no write at all if zero principles are flagged, or if the user declines every candidate)

Behavior notes

  • Constitution is special: version-bump semantics (MAJOR/MINOR/PATCH), a prepended Sync Impact Report comment, and the version line at the bottom are all handled here.
  • [OPEN: ...] is reserved for genuine undecided design questions. Known code-vs-artifact violations never get narrated into an artifact body — they belong in DEFECTS.md via /ardd-defects.
  • Production shortcuts are recorded under a ## Production Annotations heading, never inline elsewhere — that heading is what /ardd-plan and /ardd-audit scan for. Refine moves stray inline ones there.
  • With no inline guidance it asks up to 3 targeted clarifying questions — never questions answerable by reading other artifacts.
  • Delta-scoped capture: capabilities newly introduced or materially changed by this refine that have no register entry (any status) and no implementation are offered in one batched confirmation and, if accepted, created backlogged in .project/features/ — never a re-prompt about the artifact's long-standing scope. On the create path the whole new artifact is the delta.
  • Ends by running /ardd-status (once per single-artifact run; once after the whole pass in no-argument mode).
  • Review mode (--review, constitution-only): audits every declared principle for continued relevance, grounded in the current project's artifacts and codebase rather than the principle's own prose. Flagged trim-candidates are presented in one batched confirmation (accept/decline per item, never all-or-nothing, never one-at-a-time) — the same shape as /ardd-plan step 3c's proposed-changes-then-confirm UI. Declined candidates are not persistently suppressed; a later --review run re-derives judgment fresh.
  • /ardd-init — the one-time initial seeding this skill takes over from
  • /ardd-audit — challenges whether the recorded decisions are good; refine applies decisions you've made