Rite Spec

$rite-spec: investigate and write the spec

Investigate and resolve material gaps into a placed, covered spec.md. $rite-clarify audits topology next. Write no plan, task, or code here.

Use $rite-quick for a typo, copy/config edit, or one-function fix. It returns here for auth, data, migration, public API, or multi-slice work.

Rules consulted (read on demand from .agents/skills/devrites-lib/reference/standards/)

Pull documentation.md for significant decisions and principles.md for declared invariants; an unavoidable principle violation is blocking. For behavioral/high-risk acceptance, use spec-grammar.md plus workspace schema; simple criteria stay flat AC-###. Apply acceptance-criteria.md so each is binary and observable. Use edge-case-trace.md to populate only relevant edge/prohibition rows. The spec's applicability map routes topology, data, integration, security, and delivery concerns to their focused standard; load a routed standard to discover required behavior, not to prescribe implementation.

Operating rules (DevRites core)

• No silent assumptions or guessing; prefer conventions; ask on scope, placement, data, UX, security, migration, or acceptance changes.
• Root authority: controlling chat asks humans, decides, and writes workspace; evidence work follows agents.md.
• Author one section at a time: problem → goal → requirements → acceptance → edges. For contested requirements/boundaries/assumptions, apply elicitation.md before continuing.

Workflow

0. Read core; if .devrites/ACTIVE exists, require its state.md. 0a. Adoption check. For a never-adopted existing codebase, route first to $rite-adopt with $ARGUMENTS; it derives baseline spec/principles. HITL offers ranked adopt-first and spec-only choices; permitted AFK adopts. Silently skip greenfield/onboarded projects, and never block solely on absence:

   if [ ! -d .devrites/archive ] \
      && [ -z "$(ls .devrites/work 2>/dev/null)" ] \
      && [ -n "$(git ls-files 2>/dev/null | grep -vE '^\.(devrites|claude)/' | head -1)" ]; then
     echo "brownfield, not yet adopted → recommend $rite-adopt first (carry this idea as its next objective)"
   else echo "greenfield or already onboarded → continue spec"; fi
   

1. Understand the request ($ARGUMENTS). State outcome and underlying problem in one sentence. Completion: it includes both. 1a. Dedupe. Search local issues/PRDs, work, and archive. On a close match ask extend/adopt/new, then record the choice; otherwise continue silently.
2. Investigate: follow investigation through its complete findings and done-when gate. Discover the project's test / build/typecheck/lint commands, frontend/backend systems, and declared project guidance (PRODUCT.md, DESIGN.md, CLAUDE.md, AGENTS.md, and .devrites/principles.md when present). Consult the capability ledger, which records current system behavior (ledger.md); Polish folds accepted deltas before Review. List .devrites/specs/*/spec.md with the host filesystem and read only capabilities this feature touches. Search accepted ADRs and relevant .devrites/**/decisions.md files directly before asking the human to revisit a settled architecture, API, or auth choice. Compare exact requirement headers and meanings with the current ledger to choose ADDED/MODIFIED/REMOVED; never classify from memory. Use spec-grammar.md's singular Capability impact: declaration to name the affected capabilities and change, or give its specific none justification. Inventory affected observable behavior from current test/contract/runtime/source evidence; map each outcome to preserving REQ/AC. Greenfield none needs the template's specific justification. Identify proof constraints now: human-only credentials, unavailable environments, approval windows, or acceptance not observable through existing test/runtime/browser surfaces. An unfamiliar framework/version routes to devrites-source-driven; missing or contradictory documentation is evidence to reconcile, never a license to guess. Split independent placement, blast-radius, and external-fact questions into at most three bounded devrites-evidence-scout tasks on one frozen candidate. Wait for and reconcile every cited dossier before step 4. The scout supplies facts only; it never asks the human or writes the spec.
3. Gather design references when provided: references-intake. The human may attach screenshots, mockups, a Figma link, a video, links, or nothing. Skip this step when none are provided. Otherwise, view or fetch them, save local files into .devrites/work/<slug>/references/, and index them in references.md as target, constraint, or inspiration. Later phases honor that role rather than treating every reference as a fidelity target. Completion: every supplied reference is saved and classified, or absence is explicit. 3a. Shape UX/UI before code when the feature is frontend (frontend-trigger). Apply devrites-ux-shape within the spec phase. It turns the references and spec into a feature-level design-brief.md (design direction, key states, interaction model, optional Figma/image visual-direction probe) that $rite-build targets for the build. In HITL it pauses for the human to confirm the direction; in AFK it asserts the best guess and logs it. Pure backend/data/CLI features skip this.
4. Resolve human-owned gaps. Recommend an option and let the human decide. Apply question-protocol, the shared afk-hitl.md option-set and decision-ownership rules, and interview-patterns.md for a vague ask. Every material dimension is resolved by a human pick or explicitly deferred as non-blocking; only genuinely reversible, low-impact details go to assumptions.md. A paper-only uncertainty may take one scoped $rite-prototype detour. A declared-principle conflict remains blocking until the human approves a recorded, scoped exception. 4a. Build-interruption forecast. Search first, then list and close foreseeable human needs: product/acceptance ambiguity, irreversible/external approval, or human-only access. Record owned prerequisites. Keep a build checkpoint only for unavailable pre-code evidence or a mandatory action-time approval. Completion: no foreseeable human choice is deferred.
5. Create or update the workspace + set .devrites/ACTIVE from state-workspace. If the slug already exists, update the existing workspace rather than overwrite it; preserve history and unrelated settled content. Write every required artifact and conditional annex exactly from spec-template (ai-spec-template), including its capability impact, existing-behavior preservation, grammar/delta, stakeholder/constraint/invariant, failure/recovery, applicability, coverage-seed, qualified backstop, edge/prohibition, UI, and AI rules. Native hierarchical instructions remain stable; do not rewrite AGENTS.md or CLAUDE.md for the active workspace. 5a. Check the spec prose with spec-checklists. Emit every applicable domain checklist and fix each CRITICAL by correcting the spec, never by softening the question.
6. Run the complete readiness gate at the bottom of spec-template, then apply the Native grammar re-read checklist in spec-grammar.md to the complete saved spec.md. Re-open the file after corrections and verify every applicable item; there is no parser or replacement script. Natively compare deltas with the current ledger using exact header semantics and the ledger's complete-block preservation rule. tasks.md deliberately does not exist yet; cross-artifact traceability starts in $rite-define. Any grammar or delta failure blocks. The interruption forecast must be resolved, owned, or a justified action-time gate. Then write Spec gate: passed <iso>. 6a. Existing-spec delta. For a pre-existing slug/workspace, compare old/new spec and questions, then show Acceptance delta (added/removed/reworded IDs) and Open-question delta (opened/resolved/reworded IDs), using none for empty categories. Show before proceeding; new workspaces skip. 6b. Review-before-code digest. Before planning, render the compact human review: Intent (one sentence), Done means (top acceptance/scenario IDs), Scope/risk (what is in/out plus the hard gates), and Build exactly this? (yes → next phase; no → revise now). The digest is a view over spec.md, not a new artifact. Stop after the digest.

Mid-flight discipline. Do not skip investigation, gap resolution, or placement decisions. See anti-patterns.

Output

When the ask overlaps the ACTIVE feature (same intent, >50% scope), route to $rite-plan revise (its gate decides) rather than minting a parallel workspace.