Skip to main content

Spec / Prior-Art Reconciliation

Use when reconciling a spec draft with existing repos.

When to Use​

Use this when the owner hands over a spec draft (from another tool or session) and asks to reconcile it with a repository, scaffold, or earlier program. The output is a set of draft documents on a branch, followed by a stop for approval. Never write a design, plan, or code in the same pass. Build order still follows build-artifact-chain.

Procedure​

  1. Inventory the live state; don't trust the spec's description of it.
    • Clone the named repo. List its branches with each one's last commit, its issues with milestones, and its PRs.
    • Diff each work branch against main by directory (git diff --name-only main...origin/<b>) to see what each one really adds.
    • Search /root/Working/Projects and /root/Working/Operations for sibling projects that overlap: controllers, control planes, runtimes, schedulers.
    • Check MemPalace for prior sessions on the program. Also check the local scaffold or zip, and its assessment files.
    • Why: specs written off-host describe a repo as it was when they were written. The repo may since have been retargeted or repopulated by other work.
  2. Resolve the GitHub owner token by probe, not assumption. Try ghtok <owner> against a known-private repo of that owner. On 401 or 404, try the owner token in the environment (for example $GITHUB_PERSONAL_ACCESS_TOKEN). Pass it process-locally with GIT_CONFIG_COUNT/extraheader and redact output. A wrong-token 404 is not absence.
  3. Preserve stranded material before changing anything. If a scaffold exists only on disk or in a zip:
    • Verify the zip and the tree match file for file (use Python zipfile if unzip is missing).
    • Secret-scan it.
    • Commit it untouched as an orphan branch baseline/<name>-<date>. Never commit it to main.
    • Read it back via the API: tree blob count and truncated:false.
  4. Ask decision questions with ponytail framing (one clarify call, at most 5 independent questions):
    • Offer the lazy option first and state its cost.
    • Cover repo shape, trust model, the fate of big subsystems, output scope, and overlap with sibling projects.
    • Adopt the owner's answer fully when they pick the broader scope. Don't re-argue it in the documents.
  5. Look for accepted decisions the new direction contradicts: ADRs, threat models, and owner-authorization docs on any branch. Name the supersession in the new spec and propose a successor ADR. Never edit the accepted record.
  6. Write the document set on a docs/<program>-v<next> branch off origin/main, per references/document-set.md (file set and the shape of each file).
  7. Deliver and stop. Commit with a draft/unapproved body, push, and read back the ref and each file at the pushed SHA. Confirm main did not move. Copy the files to /root/Working/Projects/<program>/ and attach every one via MEDIA:.

Always-on rules​

  • Roles only. No model or provider names in roles, runbooks, or spec requirements. Route bindings belong in owner-set config and receipts. Existing files that name models are listed for retirement.
  • Separate authority from judgment. When the design has an agent "chief of staff" or coordinator, keep lifecycle state (claims, leases, fences, sweeping, watchdog) in deterministic code. The model supplies judgment only. Credentials sit with a separate broker, never in agent processes.
  • Name overlap explicitly. When a sibling project designs the same component, make "merge, layer, or keep separate" a decision with a recommendation. Don't silently absorb or ignore it. When two components share a name across projects, say so in both places.
  • Qualify limited results. A 403 on a settings, ruleset, or protection endpoint means the credential lacks permission; record it as unverified. Count gap-list totals mechanically; don't estimate them.
  • Follow the firm's writing standards in deliverables: no em dashes, Oxford comma, acronyms spelled out. Grep for — before committing.
  • Lead the reply with what the repo actually contains when it differs from the spec's premise. Then give pushed SHAs, how each owner idea landed, blocking decisions with recommendations, and unverified items.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/spec-prior-art-reconciliation/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/spec-prior-art-reconciliation/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-04.