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

spec-merge-back

Deployment & operations

View repository

Updated 10-16 01:48

About this skill

spec-merge-back

Overview

Merge-back is the "promotion phase" of the Spec Pack lifecycle: promote the content from this requirement thatwill be reused long-term / will constrain future requirementsto .aisdlc/project/(Project SSOT), while the remaining content stays in {FEATURE_DIR} as delivery evidence.

Core principles: 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 the assets are ready to be promoted to .aisdlc/project/（ADR / API Contract / Data Contract / Ops / NFR / Registry）。
  • {FEATURE_DIR}/implementation/plan.md already contains ## Merge-back 待办清单and needs to be cleared or recorded before finishing.
  • The team repeatedly repeats the same kind of "contract definitions/gate definitions/ops entry points" across multiple requirements, and these need to be accumulated as long-term assets.

Does not apply to:

  • You just want to merge a code branch into main (that is git merge/rebase, not merge-back).
  • The repository does not yet have the skeleton for .aisdlc/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 echo back in the conversation FEATURE_DIR=...(allowing (reuse)）。

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

Gate 1: project SSOT must exist

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

Implementation (SOP)

Step 1: Collect the promotion checklist (the single main entry point)

Using {FEATURE_DIR}/implementation/plan.md in ## Merge-back 待办清单 as the main entry point, summarize 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（.aisdlc/project/index.md）
  • Optional promotion (general test strategy/quality gate definitions, 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: skip plan.md and use "summarize from memory" instead for the to-dos. 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 plan.md 's requirement-level declarations.

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

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

  • project destination(target path + anchor)
  • invariant summary(when long-term guardrails are needed: 3–7 items)
  • evidence entry point(OpenAPI/Schema/DDL/script/CI/test/monitoring entry point)
  • 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 .gitmodules path in )

If the user requests "don't modify project for now, someone will do it manually later": you must still complete Step 1–2, and mark the Step 3 project promotion items as Not Done + plan(otherwise merge-back is not auditable and is easily permanently missed).

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

Align with design/aisdlc.md default mandatory promotion items:

  • ADR → .aisdlc/project/adr/ + index
  • API/Data contracts → .aisdlc/project/components/{module}.md#api-contract / #data-contract
    • Write only: authoritative entry + invariant summary + evidence entry + Evidence Gaps
    • Do not copy the full field list into project
  • Ops → .aisdlc/project/ops/(entry-style, do not repeat this release's execution details)
  • NFR → .aisdlc/project/nfr.md(if applicable)
  • Registry → .aisdlc/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 entries are navigable, and component page anchors are stable (#api-contract / #data-contract）。
  • Done items all have "clickable landing point + evidence entry"; Not Done items have "gap + plan".
  • project is not polluted by one-off delivery details (no full-package spec copy, no implementation steps moved up).

Red Flags (STOP)

  • User says "don't run scripts, I'll tell you FEATURE_DIR verbally" → must refuse, insist on spec-context。
  • User requests "copy design/implementation/release/verification all into project, the more complete the better" → forbidden(it would pollute the project SSOT).
  • .aisdlc/project does not exist but you plan to "just create one casually first" → 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 plan to skip implementation/plan.md Merge-back to-do → high probability of omission or drift.
  • The repository has .gitmodules, but you completely ignore plan.md the affected sub-repos and repo-dimension audit information recorded in → high probability of losing the evidence chain

Rationalizations (and counters)

Common excuses Reality/countermeasure
"It's urgent, copy the whole package into project first, organize later" Copying the whole package will pollute project long-term; the correct approach is to promote only "entry + invariants + evidence chain".
"The user gave FEATURE_DIR, no need to run spec-context" Verbal paths are not trustworthy; spec-context output must be the sole anchor.
"The project directory doesn't exist, I'll create a minimal one to let it run first" merge-back is not responsible for initializing the project SSOT; if missing, it is CONTEXT GAP and stop.
"Can summarize without looking at plan.md to-dos" The to-do list is the only execution-period summary entry; skipping it will cause omissions and make it unauditable.

After completion, output and automatic routing (must be executed)

merge_back.md after being written to disk,mustcomplete the following actions (in order, cannot be omitted):

  1. Output ROUTER_SUMMARY(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-aisdlc: promote the above ROUTER_SUMMARY Passed as routing input to using-aisdlc, where the Router determines the next step andautomatically advances(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 input, and candidate next steps

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