--- name: speckit-workflows.incorporate description: Incorporate documents into an existing or new workflow and advance stages intelligently compatibility: Requires spec-kit project structure with .specify/ directory metadata: author: github-spec-kit source: templates/commands/workflows.incorporate.md --- # Speckit Workflows.Incorporate Skill The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty). User input: $ARGUMENTS ## Overview Incorporate external documents (specs, plans, research, checklists, etc.) into existing workflows or initiate new workflows using the document as context. This command intelligently: 1. **Detects document type** - Identifies what kind of document it is 2. **Detects workflow context** - Determines if you're in a workflow and at what stage 3. **Advances workflow stages** - Automatically progresses to appropriate stage 4. **Leverages analysis** - Uses `/speckit.analyze` for intelligent incorporation ## Usage ```bash /speckit.workflows.incorporate [--type TYPE] [--workflow WORKFLOW] [--stage STAGE] [--enrich] [--dry-run] ``` **Options:** - `--type TYPE` - Force document type (spec|plan|tasks|research|checklist|postmortem) - `--workflow WORKFLOW` - Initiate specific workflow if not in one (baseline|bugfix|enhance|modify|refactor|hotfix|deprecate|cleanup) - `--stage STAGE` - Target stage (auto|current|spec|plan|tasks) - `--enrich` - Enrich current stage docs instead of advancing (default for research) - `--dry-run` - Show what would be done without making changes ## Step 1: Load Workflow Context First, get current workflow context: ```bash cd "$(git rev-parse --show-toplevel)" && \ source .specify/scripts/bash/common.sh && \ CURRENT_BRANCH=$(get_current_branch) && \ echo "Current branch: $CURRENT_BRANCH" && \ get_feature_paths ``` This provides: - `CURRENT_BRANCH` - Current git branch - `FEATURE_DIR` - Feature directory path (if in workflow) - `FEATURE_SPEC` - Main specification file - `IMPL_PLAN` - Implementation plan file - `TASKS` - Task list file **Determine workflow stage:** - If `FEATURE_DIR` not found -> Not in workflow - If only spec exists -> Spec stage - If spec + plan exist -> Planning stage - If spec + plan + tasks exist -> Task stage ## Step 2: Analyze the Document Use native spec-kit analyze to understand the document: ```bash /speckit.analyze ``` **From the analysis, identify:** 1. **Document Type** - What kind of document is this? - **Spec/Requirements** - Goals, acceptance criteria, architecture - **Plan/Approach** - Implementation steps, technical decisions - **Tasks** - Concrete action items, checklist format - **Research** - Background info, API docs, examples, findings - **Checklist** - Validation items, testing scenarios - **Post-mortem** - Incident analysis, lessons learned 2. **Key Content Areas** - Main sections and topics covered 3. **Completeness** - Is it comprehensive or partial? 4. **Conflicts** - Does it contradict existing workflow docs? **Detection Patterns:** - **Spec indicators**: "Requirements", "Goals", "Acceptance Criteria", "Architecture", "User Stories" - **Plan indicators**: "Implementation", "Approach", "Technical Design", "Steps", "Strategy" - **Tasks indicators**: Checkbox lists, numbered action items, "TODO", "Task", specific assignments - **Research indicators**: "Background", "Investigation", "Findings", "Documentation", external links - **Checklist indicators**: Validation lists, test scenarios, "Verify", "Ensure", "Check" ## Step 3: Determine Action Strategy Based on workflow context and document type, choose strategy: ### Scenario A: Not in Workflow (No FEATURE_DIR) **Action: Initiate Workflow** 1. If `--workflow` specified, use that. Otherwise, determine from document content/type: - If the document is a plan, task list or both: - Contains "enhance", "feature", "improvement" or refers to new functionality -> enhance - Contains "bug", "fix", "regression" or refers to an issue with existing functionality -> hotfix - If the document is a spec: - Contains "feature", "enhance", "improvement" or refers to new functionality -> feature or enhancement depending on complexity - Contains "refactor", "cleanup", "optimize" -> refactor - Contains "deprecate", "remove", "sunset" -> deprecate (ask user which feature to deprecate if unclear) - Contains "baseline", "context", "current state" -> baseline - Contains "bug", "fix", "regression" -> bugfix or hotfix depending on complexity - Otherwise -> Ask user for workflow type 2. Save the document to a temporary location, with appropriate naming (e.g., `spec.md`, `bugfix.md`, `plan.md` etc.) 3. Execute the appropriate handoff to create the workflow: - For feature/enhancement: `/speckit.specify` or `/speckit.enhance` - For bugfix/hotfix: `/speckit.bugfix` or `/speckit.hotfix` - For refactor: `/speckit.refactor` - For deprecate: `/speckit.deprecate` - For baseline: `/speckit.baseline` ### Scenario B: Currently **in** Workflow - Document Type Matches Current Stage **Action: Enrich Current Stage** Append or merge document content into existing stage document. ### Scenario C: Current **in** Workflow - Document Type is Next Stage **Action: Advance to Next Stage** **C1: Have spec, document is plan** ```bash /speckit.plan # Then incorporate plan content into plan.md ``` **C2: Have spec + plan, document is tasks** ```bash /speckit.tasks # Then incorporate task content into tasks.md ``` ### Scenario D: Current **in** Workflow - Document Type Skips Stages **Action: Create Intermediate Stages, Then Advance** **Example: Have spec only, document is tasks** 1. First, create minimal plan: ```bash /speckit.plan ``` 2. Then, create tasks using document: ```bash /speckit.tasks ``` ### Scenario E: Document Type is Research/Checklist **Action: Enrich Most Relevant Stage Document** Research and checklists are supplementary - don't advance stages, just enrich: - **Research** -> Add to spec.md (background section) or plan.md (approach section) - **Checklist** -> Add to tasks.md (validation section) or create separate checklist.md ## Step 4: Intelligent Incorporation When incorporating document content: ### 4.1 Check for Conflicts Compare document with existing content: ```bash # If conflicts detected by analyze # Present to user: echo "Potential conflicts detected:" echo " - Document says X" echo " - Existing spec says Y" echo "" echo "Options:" echo " 1. Keep existing (skip conflicting parts)" echo " 2. Replace with new (update existing)" echo " 3. Mark as NEEDS RECONCILIATION (both present)" ``` ### 4.2 Detect Duplicates If analyze indicates overlapping content: - Skip truly duplicate content - Merge complementary information - Note: "Incorporated X from document, skipped Y (already covered)" ### 4.3 Structure Content When adding to existing docs: - Maintain document structure (use existing headers) - Add new sections if needed - Preserve formatting consistency - Add source attribution: `` ### 4.4 Preserve Git History Before making changes: ```bash # Ensure changes are trackable git diff --exit-code || echo "Uncommitted changes exist" ``` ## Step 5: Provide Feedback Clearly summarize what was done: ``` Incorporated document: research-notes.md Actions taken: - Detected document type: Research - Current workflow: bugfix/001-login-error - Current stage: Spec - Action: Enriched bug-report.md with research findings Added sections: - Background on authentication flow - API documentation excerpts - Similar bug references Next steps: - Review incorporated content in bug-report.md - Run: /speckit.plan (when ready to move to planning) ``` ## Step 6: Suggest Next Actions Based on workflow state after incorporation: ``` Workflow Progress: [done] Spec - bug-report.md (enriched) [ ] Plan - Ready to create with: /speckit.plan [ ] Tasks - Awaiting plan completion Suggested: Review the enriched spec, then run /speckit.plan to continue. ``` ## Error Handling ### Document Not Found ``` Error: Document not found: nonexistent.md Please check the path and try again. ``` ### Cannot Determine Workflow Type ``` Cannot determine appropriate workflow type from document. Please specify: /speckit.workflows.incorporate document.md --workflow [type] Available workflows: baseline, bugfix, enhance, modify, refactor, hotfix, deprecate, cleanup ``` ### Conflicts Detected ``` Conflicts detected - user input required Cannot auto-merge due to contradictions. Please resolve manually or use: --force-append (add as-is with conflict marker) --skip-conflicts (skip conflicting sections) ``` ## Best Practices 1. **Use analyze first** for unfamiliar documents 2. **Review enriched docs** before advancing stages 3. **Commit after incorporation** to preserve history 4. **Use --dry-run** for complex incorporations 5. **Specify --type** if detection might be ambiguous 6. **Keep original documents** (don't delete after incorporation) ## Integration with Other Commands - **`/speckit.analyze`** - Review after incorporation to address conflicts or inconsistencies - **`/speckit.plan`** - Called automatically when advancing to plan stage - **`/speckit.tasks`** - Called automatically when advancing to tasks stage - **Workflow creation scripts** - Called when initiating new workflows --- **Note**: This is a command extension - it doesn't create workflow structures itself, but works with existing workflows and delegates to appropriate workflow commands/scripts.