--- name: speckit-reconcile-run-12c9f9eeff6e description: Reconcile implementation drift by updating the feature's own spec, plan, and tasks compatibility: Requires spec-kit project structure with .specify/ directory metadata: author: github-spec-kit source: reconcile:commands/reconcile.md --- Act as the **Chief Software Architect** and **Implementation Auditor**. A feature implementation has landed, but "artifact drift" has been discovered (e.g., missing routes, updated behavior, or unlinked UI). Your goal is to **reconcile** this drift by surgically amending the feature's own specification, plan, and task artifacts. ## User Input ```text $ARGUMENTS ``` ### Input Parsing The input `$ARGUMENTS` is a **Gap Report** — a natural language description of what is missing or changed in the implementation versus the documentation. **Examples:** - "Backend + tests for Invoice Settings exist; React screen scaffolded. Users can't navigate to it. Need sidebar link + route." - "The /api/v1/settings endpoint now requires an 'org_id' header not in the original plan." If `$ARGUMENTS` contains any of these flags, respect them (optional): - `--spec-only` — update only `spec.md` - `--plan-only` — update only `plan.md` - `--tasks-only` — update only `tasks.md` If `$ARGUMENTS` is empty, output `ERROR: No gap report provided. Usage: /speckit.reconcile.run [gap report text]` and stop. --- ## Step 0: Discovery & Setup (Gate) ### 0.1 Resolve Paths Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only --include-tasks` to identify the active feature directory and its artifacts. This script is mandatory for path discovery. If the script is missing, stop and inform the user. Derive absolute paths for: - `FEATURE_DIR` (e.g., `specs/###-feature-name/`) - `FEATURE_SPEC` (`FEATURE_DIR/spec.md`) - `IMPL_PLAN` (`FEATURE_DIR/plan.md`) - `TASKS_FILE` (`FEATURE_DIR/tasks.md`) **Validation**: Ensure `spec.md` and `plan.md` exist. If either is missing, stop with: > ⚠️ Missing required files in `FEATURE_DIR`. Expected: spec.md, plan.md. > Run `/speckit.specify` and `/speckit.plan` first. If `tasks.md` does not exist, create it with a `## Remediation: Gaps` heading before appending tasks. ### 0.2 Load Context Read `FEATURE_SPEC`, `IMPL_PLAN`, and `TASKS_FILE`. Also read `.specify/memory/constitution.md` if it exists. If found, extract MUST-level constraints and Architecture Standards. These are enforced in Step 1 — any remediation item that conflicts with a MUST principle is flagged as CRITICAL: ``` 🔴 CONSTITUTION CONFLICT: [remediation item] conflicts with [principle] → This must be resolved in Step 2 clarification before edits proceed. ``` --- ## Step 1: Gap Normalization Analyze the user's **Gap Report** and normalize it into structured remediation items: | Category | Typical Issues | Action | |----------|----------------|--------| | **Wiring & Navigation** | Missing routes, menu items, sidebar links | Add to `plan.md`, create tasks in `tasks.md` | | **Contracts** | API field mismatches, missing headers | Update `plan.md` contracts, create tasks | | **Acceptance Criteria** | Implementation behaves differently than planned | Update `spec.md` scenarios/criteria | | **Test Coverage** | New wiring/navigation without verification | Add task for Integration Test | | **Logic/UX** | Success toasts missing, error handling gaps | Add tasks for implementation | For each normalized item, verify it does not conflict with any MUST-level constitution constraint loaded in Step 0.2. Flag any conflicts as CRITICAL and include them in Step 2 clarification. --- ## Step 2: Clarify (Exactly Once; Max 5 Questions) If the gap report is ambiguous (e.g., "the button doesn't work" without saying which button), ask targeted questions. Use this format and **wait for answers**: ```markdown ## Question [N]: [Topic] **Context**: [Relevant implementation detail] **Decision Needed**: [1 sentence] **Suggested Answers**: [Table with Option A/B/C] **Your choice**: _[Wait for user response]_ ``` **Rules:** - Max 5 questions. - Max 3 unresolved `NEEDS CLARIFICATION` markers in output — beyond that, pick reasonable defaults and note them in the Sync Impact Report. - Proceed with reasonable defaults if questions aren't strictly necessary. --- ## Step 3: Impact Map Before making any edits, produce a brief impact map: ```markdown ### Sync Impact Map | Artifact | Changes | Tasks Generated | |----------|---------|-----------------| | `spec.md` | Update AC-04, add User Scenario "Error Handling" | None | | `plan.md` | Add Route `/settings`, update API contract | None | | `tasks.md` | Append remediation tasks | T045, T046, T047 | ``` --- ## Step 4: Reconciliation (Surgical Edits) **Constraint**: Operate strictly in place. Do not create branches, switch branches, or run feature-creation scripts. All edits target existing files in `FEATURE_DIR`. ### 4.1 Update Specification (`spec.md`) - **Acceptance Criteria**: Amend existing criteria or add new ones to reflect the shipped reality. - **User Scenarios**: Add missing scenarios discovered during implementation (e.g., specific edge cases). - **Revision Note**: Add a block at the bottom: ```markdown ### Revision: Implementation Sync [YYYY-MM-DD] - Reason: [Summary of drift reconciled] ``` ### 4.2 Update Plan (`plan.md`) - **Routing & Navigation**: Add any missing routes, endpoints, or UI wiring details. - **Integration Contracts**: Update API schemas, request/response headers, or payloads. - **Testing Strategy**: Ensure the strategy covers the newly identified gaps. - **Revision Note**: Append a revision note (same format as spec.md) if plan sections were modified. ### 4.3 Update Tasks (`tasks.md`) This is the most critical step. Create remediation tasks to close the drift. **Task Formatting**: `- [ ] T{NNN} [P] [{story}] {action verb} {what} in {exact/file/path.ext} [Sync: Gap Report]` Where `[P]` is an optional priority flag — include it only for tasks that are blocking or high-urgency. Omit for normal priority. The `[Sync: Gap Report]` tag is always appended for traceability. **Rules for Tasks**: 1. **Increment IDs**: Find the highest `T###` in `tasks.md`. Start new tasks from `max + 1`. Never reuse or renumber. 2. **Phase Placement**: Place new tasks under the relevant User Story phase (e.g., `## [US2] Settings Dashboard`). If no phase fits, create a `## Remediation: Gaps` section at the end. 3. **Exact Paths**: Every task MUST include an exact file path where the change is needed. 4. **Mandatory Integration Test**: If you identified a **Wiring & Navigation** gap, you MUST add a task for an Integration Test to verify it. --- ## Step 5: Sync Impact Report Output the final report: ```markdown # Sync Impact Report ## Changed Files | File (absolute path) | Change Summary | |----------------------|----------------| | `/absolute/path/to/spec.md` | Updated AC, Scenarios | | `/absolute/path/to/plan.md` | Updated Routing/Contracts | | `/absolute/path/to/tasks.md` | Added [N] remediation tasks | ## New Remediation Tasks [List the new tasks added, e.g.] - **T045**: Add sidebar link in `src/components/Sidebar.tsx` - **T046**: Update router in `src/router/index.ts` - **T047**: Integration test: navigate to Settings in `tests/integration/navigation.test.ts` ## Outstanding Decisions [List any `NEEDS CLARIFICATION` items or "None"] ## Next Step [Recommend based on what changed:] - If remediation tasks were added → `/speckit.implement` to execute them - If plan was significantly updated → `/speckit.plan` to review architecture - If only spec was updated → Review changes and proceed with implementation ``` --- ## Done Criteria - Gap report parsed and categorized. - Feature's own `spec.md` and `plan.md` surgically updated. - `tasks.md` updated with incremented `T###` IDs and exact file paths. - Mandatory integration test task added for wiring gaps. - Revision note added to artifacts. - Sync Impact Report printed. --- Source attribution: eitatech Original project: https://github.com/eitatech/gatomia-vscode/blob/081a9aadc7c7680b5b2b4f728042dc2a9f7e8dcc/.agents/skills/speckit-reconcile-run/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 atman-33 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: eitatech Original project: https://github.com/eitatech/gatomia-vscode/blob/081a9aadc7c7680b5b2b4f728042dc2a9f7e8dcc/.agents/skills/speckit-reconcile-run/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management, Sales Roles: Backend Developer, Product Manager, QA / Test Engineer, Sales Development Rep (SDR), Technical Product Manager Specialties: Backend Tools: Spec Kit Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: da234807b18cecd0df195312e6102aec103f1c2746f15a361b348982547d3900