SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsspec-merge-back

spec-merge-back

General & other

View repository

Updated 10-16 08:49

About this skill

spec-merge-back

Overview

Merge-back is the "promotion stage" of the Spec Pack lifecycle: promote what belongs to this requirementwill be reused long-term / will constrain future requirementscontent into .aidlc/project/(Project SSOT), while the rest remains in {FEATURE_DIR} as delivery evidence.

Core principle: Project SSOT only accumulates entry points + guardrails (invariants) + evidence chain; it is forbidden to move "one-off delivery details" into the project.

When to Use

Applies to:

  • This requirement is complete and you are preparing to promote assets into .aidlc/project/（ADR / API Contract / Data Contract / Ops / NFR / Registry）。
  • {FEATURE_DIR}/implementation/plan.md already contains ## Merge-back 待办清单, which needs to be cleared or recorded before finishing.
  • The team repeatedly duplicates the same kind of "contract conventions / gate conventions / ops entry points" across multiple requirements and needs to accumulate them as long-term assets.

Does not apply to:

  • You merely want to merge a code branch into main (that is git merge/rebase, not merge-back).
  • The repository does not yet have the skeleton of .aidlc/project/ (this is CONTEXT GAP, and you should first use project-discover* or the project initialization process to establish the project SSOT).

Core Pattern (Gates first)

Gate 0: FEATURE_DIR must be located (verbal paths are forbidden)

REQUIRED SUB-SKILL: currently executing spec-context to obtain context, and echoing in the conversation FEATURE_DIR=...(allowed (reuse)）。

stop on failure：Get-SpecContext stop on error; "write a version first / guess the path first" is not allowed.

Gate 1: the project SSOT must exist

  • Must exist:.aidlc/project/
  • Does not exist: output CONTEXT GAP: .aidlc/project missing and stop ("just create any directory as long as it runs" is forbidden).

Implementation (SOP)

Step 1: Collect the promotion checklist (the only main entry)

Use {FEATURE_DIR}/implementation/plan.md in ## Merge-back 待办清单 as the main entry, aggregate the items to be promoted this time, and group them by category:

  • ADR (key decisions)
  • API Contract (by module)
  • Data Contract (by module)
  • Ops（runbook/monitoring/rollback）
  • NFR (if applicable)
  • Registry（.aidlc/project/index.md）
  • Optional promotion (general test strategy / quality gate conventions, etc.)
  • If the repository has .gitmodules: combine with the affected sub-repositories declared in plan.md to confirm which evidence comes from the root project and which comes from sub-repository paths

Forbidden: skipping plan.md todos and instead "summarizing from memory". If time is tight, you may use git diff to supplement evidence, but the checklist source is still mainly plan.md ;.gitmodules only provides static sub-repository path facts and does not replace the requirement-level declarations of plan.md .

Step 2: Generate/update {FEATURE_DIR}/merge_back.md(checklist and evidence)

{FEATURE_DIR}/merge_back.md is therequirement-level SSOTof this merge-back: each item must clearly state:

  • project landing point(target path + anchor)
  • invariant summary(when long-term guardrails are needed: 3–7 items)
  • evidence entry(OpenAPI/Schema/DDL/script/CI/test/monitoring entry)
  • status: Done / Not Done (for Not Done, the gap and plan must be written)
  • code source(root project / sub-repo path; if from a sub-repo, reference the path in .gitmodules )

If the user requests "don't change the project for now, someone will do it manually later": Steps 1–2 must still be completed, and the project promotion item in Step 3 must be marked as Not Done + plan(otherwise merge-back is not auditable and is easily missed permanently).

Step 3: Promote to the project SSOT (only promote long-term assets)

Align with the default must-promote items of design/aidlc.md :

  • ADR → .aidlc/project/adr/ + index
  • API/Data contract → .aidlc/project/components/{module}.md#api-contract / #data-contract
    • Write only: authoritative entry point + invariant summary + evidence entry point + Evidence Gaps
    • It is forbidden to copy the full field list into the project
  • Ops → .aidlc/project/ops/(entry-point style, do not repeat the execution details of this release)
  • NFR → .aidlc/project/nfr.md(if applicable)
  • Registry → .aidlc/project/index.md(update status to Merged & Archived or the team-agreed status)

Step 4: DoD self-check (completion criteria)

  • {FEATURE_DIR}/merge_back.md has been written to disk, covering ADR/API/Data/Ops/NFR/Registry (applicable items).
  • The project-side entry points are navigable, and the component page anchors are stable (#api-contract / #data-contract）。
  • Every Done item has a "clickable landing point + evidence entry point"; every Not Done item has a "gap + plan".
  • The project is not polluted by one-off delivery details (no wholesale copying of the spec, no moving implementation steps up into it).

Red Flags (STOP)

  • The user says "don't run the script, I'll tell you FEATURE_DIR verbally" → must refuse, and insist on spec-context。
  • The user requests "copy design/implementation/release/verification all into the project, the more complete the better" → forbidden(it would pollute the project SSOT).
  • .aidlc/project does not exist but you are about to "just create something quickly" → forbidden(CONTEXT GAP, first create the project SSOT skeleton).
  • You start writing a "git merge/rebase checklist" → you have misunderstood merge-back as a git merge; stop immediately and correct it.
  • You are about to skip the Merge-back todo of implementation/plan.md → high probability of omission or drift.
  • The repository has .gitmodules, but you completely ignore the affected sub-repos and repo-dimension audit information recorded in plan.md → high probability of losing the evidence chain

Rationalizations (and counters)

Common excuse Reality/countermeasure
"It's urgent, just copy the whole package into the project first, organize it later" Copying the whole package will pollute the project long-term; the correct approach is to promote only the "entry points + invariants + evidence chain".
"The user provided FEATURE_DIR, so there's no need to run spec-context" A verbal path is untrustworthy; the output of spec-context must be used as the sole anchor.
"The project directory doesn't exist, let me create a minimal one first so it can run" merge-back is not responsible for initializing the project SSOT; if it is missing, that is CONTEXT GAP and stop.
"I can summarize without looking at the plan.md todos" The todos are the only execution-period summary entry point; skipping them will cause omissions and make it unauditable.

Output after completion and automatic routing (must be executed)

merge_back.md has been written to disk,mustcomplete the following actions (in order, not skippable):

  1. Output ROUTER_SUMMARY(in YAML form, for Router decision-making):
ROUTER_SUMMARY:
  stage: MergeBack
  artifacts:
    - "{FEATURE_DIR}/merge_back.md"
  needs_human_review: true
  blocked: false
  block_reason: ""
  notes: "已晋升 ADR/契约/ops/NFR/registry；Done/Not Done 与证据入口齐全。"

  1. Immediately execute using-aidlc: the above ROUTER_SUMMARY Passed as routing input to using-aidlc, where the Router determines the next step andautomatically proceeds(without waiting for the user to say "continue").

    • If the Router determines that it can automatically continue: continue executing the next worker skill within the same conversation turn
    • If the Router triggers a hard interrupt: stop and output the blocking reason, the required inputs, and candidate next steps

  2. Conversation output: Before calling using-aidlc, you may briefly state "The artifacts for this stage have been written to disk; now calling using-aidlc to route the next step."