agentleFS
geekxxgeekxx/ai-assistant-starter-kit/.claude/skills/fd-reconcile/SKILL.md

fd-reconcile

Skill1 starsChanged 4 months agoMITView on GitHub

Symmetric PRD-to-TDD reconciliation for a Forward Deploy firm — finds every place the Intuit PRD and the firm-authored TDD diverge, classifies each divergence as one of four types, and writes the open-decisions seed that feeds the Phase 2 Design build gate (Deliverable 2). Sol dispatches Vantage (Fable) to do the analysis; Sol reviews and delivers. Trigger on "reconcile [firm]," "run the reconciliation," "PRD TDD diff," "where do the specs disagree." It surfaces divergences; it never picks which fact wins, never resolves a conflict, never treats either document as ground truth, and never confirms a silent gap is real. It STOPS if either spec is stale.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    NOT write anywhere else and do NOT guess a path.

    line 58
  2. Very specific:

    Currency precondition: Read the staleness frontmatter status: field on both specs.

    line 68
  3. Distinctive:

    Every divergence carries section-level citations in each document.

    line 167
  4. Distinctive:

    No conflict was resolved; neither doc was treated as ground truth (watch for silent siding with the TDD).

    line 168
  5. Distinctive:

    No false conflicts that one doc already reconciles (the search-for-reconciling- statement rule was applied).

    line 170
  6. Very specific:

    Overwrite protection: if reconciliation.md already exists and contains entries whose Status is Resolved or Deferred, do NOT overwrite it.

    line 188
  7. Very specific:

    When reconciliation.md already carries closed (Resolved / Deferred) entries, Vantage produces a proposed-changes block for Jeff to approve …

    line 199
  8. Distinctive:

    Treat either document as ground truth.

    line 224
  9. Distinctive:

    Write anywhere if the firm's folder is not mounted — it fails loudly and tells Jeff to mount it.

    line 231

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- audience: internal -->

FD Reconcile

The flagship FD analytical skill: hold the Intuit PRD and the firm-authored TDD in context at once, find every place they diverge, classify each divergence, and write the open-decisions log seed the design gate consumes. Sol orchestrates and reviews; Sol never does the reconciliation itself. Sol dispatches Vantage (the Forward-Deploy Firm Intelligence Lead) to do the reasoning, then reviews and delivers. It surfaces the seams; the decisions belong to the room.

Sourced from FD-P-04 (Playbook Ch 4). Highest-stakes FD skill: its output feeds the go/no-go gate. Ported into Sol from the retired standalone FD starter-kit; paths are rebound to the shared-Drive firm-repo convention (see Step 0).

When to run

  • Jeff says "reconcile [firm]," "run the reconciliation," "PRD TDD diff," or "where do the specs disagree."
  • On ingest or re-ingest of either spec (re-ingest triggers: after the gate, after a PRD or TDD revision, after a scope-affecting SOW change).

Step 0 — Locate the firm repo (fail loudly if not mounted)

The firm repo is the firm's folder inside the canonical FD Shared Drive, mounted locally via Google Drive for Desktop. The live mount is (quote it, trailing space after "Forward Deploy"):

/Users/jeffheinen/Library/CloudStorage/GoogleDrive-jeff_heinen@intuit.com/Shared drives/MM Partner Program Central Drive/Forward Deploy /<Firm>/

The firms are FLAT — the numbered layout sits directly under <Firm>/, there is NO Forward Deploy/ wrapper inside <Firm>/. See _shared/fd-firms.md for the current firm list. Numbered layout:

<Firm>/
├── 00_delivery/        transcripts/ meeting_notes/ status/ blockers/ risk/
├── 01_artifacts/       prd/ tdd/ decks/ trackers/ raw/
├── 02_discovery/       raw/ + readouts/
├── 03_design/          open-decisions/ + gate-pack/   <- reconciliation.md lives at 03_design/open-decisions/reconciliation.md
├── 04_agents/          <AGENT-KEY>/  (flat: D3/D5/D6 deliverable docs + links.md)
└── 05_wrap/
  1. Confirm <Firm>/ exists and is writable at the path above (ls -ld; drwx = OK). Any older path — the fully-retired My Drive/Agent Studio Forward Deploy/<Firm>/ tree (superseded 2026-07-24), a per-firm .shortcut-targets-by-id/<other-ID>/, or a <Firm>/Forward Deploy/ wrapper — is STALE; resolve to the canonical Shared Drive path above instead. Only if the firm's folder is genuinely absent or read-only there do you STOP and fail loudly and tell Jeff to mount/fix it. Do NOT write anywhere else and do NOT guess a path. See the drive-folder-routing memory for the canonical rule.

Step 1 — Preconditions (this skill REFUSES, it does not degrade)

Reconciling a stale spec is worse than none: it manufactures conflicts a revision already closed and misses ones a revision opened. Refusing is correct here.

  1. Locate the current PRD in 01_artifacts/prd/ and the current TDD in 01_artifacts/tdd/. They are converted separately and never merged.
  2. Currency precondition. Read the staleness frontmatter status: field on both specs. Proceed ONLY if both read current. If either reads possibly stale, or is missing the frontmatter block entirely, STOP and tell Jeff to re-ingest that spec first. Do not reconcile.
  3. Optional but recommended: pull 02_discovery/raw/ session notes. Their "Contradictions noted" sections are the prime source of silent-gap candidates.

Step 2 — Resolve scope

Scope is the single firm named. State it in one line, confirm the firm repo is mounted (Step 0) and both specs are current (Step 1), and proceed.

Step 3 — Dispatch Vantage (one subagent)

Sol spawns Vantage to do the reconciliation. Model tier: claude-fable-5, no downgrade path — holding two full specs in context and finding the cross-document seams is deep-synthesis work, exactly Vantage's flagship lane.

The subagent has no session memory; the spawn prompt must be fully self-contained (the process-meetings dispatch pattern). Give exact paths to the PRD, the TDD, and (if used) the discovery notes, or paste them if short. Include ALL of the following.

Who Jeff is (read _shared/fd-firms.md and paste its "Who Jeff is" block verbatim into the spawn prompt — prevents the recurring role/firm errors):

Identity and grounding discipline (paste verbatim):

You are Vantage, doing a meticulous Forward Deploy PRD-to-TDD reconciliation. You never fabricate. Every divergence cites the section in each document it rests on. You do not summarize the documents; you find where they diverge. Any claim you cannot trace to a source is tagged [Unverified] inline. You end with the trace footer specified below.

House rules (paste verbatim):

  1. Grounding: every divergence cites section-level sources in each doc; anything inferred is marked [inferred] and kept separate; end with the trace footer.
  2. Roles, not names, in anything that could travel to a firm — decision owners are roles (PM / firm / EM / SME / DM), never named people.
  3. Surface, never decide: you surface divergences; the decisions are made by people in the room.
  4. Regulated-data restraint: the regulated-data conflict class (zero-ingestion vs. anonymize-at-ingestion) is filed with owner "SME / regulated-data lead, escalate," never reasoned to a resolution — it may not be the pod's to solve.

The four divergence types (paste verbatim; each finding is exactly one):

  1. Factual conflict — the two docs state different facts about the same thing.
  2. Scope conflict — in-scope in one doc, out or absent in the other.
  3. Assumption gap — one doc depends on something the other never addresses.
  4. Silent gap — neither doc covers something the build will require.

Rules block (paste verbatim — the load-bearing lines from FD-P-04):

  • Do not summarize the documents. Find where they diverge.
  • Do not resolve any conflict. Surface it; decisions are made by people in the room.
  • Do not treat either document as ground truth. They are peers. (Omitting this line caused the model to silently side with the TDD — Ch 8 feedback lesson.)
  • Before confirming any conflict, search both documents for a reconciling statement; do not flag a divergence one doc already resolves.
  • Cite section-level sources for every divergence.
  • Mark inferred (vs. stated) conflicts [inferred] and keep them in a separate section.
  • Silent-gap candidates from discovery sessions are listed as candidates for DM confirmation, never as confirmed gaps.

Output template Vantage fills (the Ch 4 shape — this file IS the open-decisions log seed, not a separate artifact):

Header: both source files with version and date, run date, open-divergence count. Per divergence:

  • What the PRD states (statement plus section citation, or "appears in only one document").
  • What the TDD states (same).
  • Type: one of the four.
  • Blocks: AGENT-01 / AGENT-02 / AGENT-03 / gate item.
  • Decision owner role: PM / firm / EM / SME / DM / needs escalation.
  • Status: Open. A separate ## Silent gaps section (each candidate with what the build needs it for and who should own it, marked as a candidate for DM confirmation). A separate ## [inferred] section for inferred (not stated) divergences. Then the trace footer:
---
**Sources:** [PRD file + version/date; TDD file + version/date; discovery notes if used]
**Claims marked [Unverified]:** [list, or "none"]

Judgment boundaries (paste verbatim):

You must NOT: pick which fact wins; judge whether a scope item is worth its cost; confirm a silent gap is real (list it as a candidate); assign a person (roles only); or touch the zero-ingestion vs. anonymize-at-ingestion regulated-data conflict beyond filing it with owner "SME / regulated-data lead, escalate."

Output contract for Vantage: return the full reconciliation content to Sol as its result. Vantage does NOT write the firm-Drive file itself and does NOT edit any existing log — Sol handles delivery and the propose-then-approve gate (Steps 4–5).

Step 4 — Sol review

  • Output is a differential, not two summaries side by side. Reject surface-reading on sight.
  • Every divergence carries section-level citations in each document.
  • No conflict was resolved; neither doc was treated as ground truth (watch for silent siding with the TDD).
  • No false conflicts that one doc already reconciles (the search-for-reconciling- statement rule was applied).
  • Silent gaps are candidates, not confirmed; inferred items are in their own section marked [inferred].
  • Regulated-data conflict filed with the escalate owner, not reasoned to a path.
  • Trace footer present.

Return to Vantage for revision if any check fails.

Step 5 — Deliver (Sol writes, with overwrite protection)

Target: <Firm>/03_design/open-decisions/reconciliation.md (flat firm path, no Forward Deploy/ wrapper; the firm repo located in Step 0). The check-fd-trace-footer.py hook watches this path; the footer must be present or the write is blocked.

  • First run / no closed decisions: Sol writes the file directly with the Write tool (creating a new file on the CloudStorage path is fine; safe-mv is only for moving an existing file).
  • Overwrite protection: if reconciliation.md already exists and contains entries whose Status is Resolved or Deferred, do NOT overwrite it. Closed decisions must never be regressed to Open. Instead run the Gate procedure below so Jeff merges new divergences into the live log without losing what the room already closed.

Give Jeff a tight chat summary: open-divergence count, the highest-stakes conflicts by agent, and any silent-gap candidates needing his confirmation.

Gate procedure (open-decisions log) — propose, never auto-edit

When reconciliation.md already carries closed (Resolved / Deferred) entries, Vantage produces a proposed-changes block for Jeff to approve rather than overwriting. Sol never edits the master silently. Pattern from process-meetings Steps 4–5.

A proposed change is a diff-style block, one entry per divergence:

  • NEW — a divergence not in the log (full Ch 4 entry, Status: Open).
  • UPDATE — an existing entry whose evidence changed (new owner, new blocked agent); show current line then proposed line, with source and date.
  • RESOLVED-CANDIDATE — an entry that notes suggest was closed; show the evidence (note, date, who decided). Jeff confirms; the tool never sets Resolved itself.
  • DEFERRAL-CHECK — any Deferred entry missing a named owner or a stated accepted consequence (Ch 5: a deferral missing either is really an open item).

On Jeff's approval: Sol writes the merged log with Write, then archives the prior version to 03_design/open-decisions/archive/reconciliation_<YYYY-MM-DD>.md. The live file is on a synced Google Drive path, so the archive move MUST go through the safe-mv skill / safe-mv.sh wrapper (--dry-run first, then real) — never raw mv/cp. A mid-sync raw move can half-move or corrupt the log.

What this skill must NOT do

  • Have Sol do the reconciliation. Sol orchestrates; Vantage analyzes.
  • Pick which fact wins, or resolve any conflict. It surfaces; the room decides.
  • Treat either document as ground truth. The PRD and TDD are peers.
  • Confirm a silent gap is real. Silent gaps are listed as candidates for Jeff.
  • Assign a named person as decision owner. Owners are roles only.
  • Reason the regulated-data conflict to a path. It is filed with the escalate owner, untouched.
  • Reconcile a stale spec. If either spec is not current, it STOPS and asks for re-ingestion.
  • Write anywhere if the firm's folder is not mounted — it fails loudly and tells Jeff to mount it.
  • Overwrite a reconciliation log that holds closed decisions. Updates go through the Gate procedure as a proposal, and the archive move uses safe-mv.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.