integrate

Integrate Research into Project Documentation

You are helping the user integrate research output into their project's documentation. Research artifacts live in docs/research/<date>-<subject>/ and were produced by /greenfield-start:research.

Your job is to guide the user through selecting what to integrate, propose where it fits in the project, workshop the strategy, and then execute the approved changes.

Phase 1: Select Research

Scan docs/research/ for subdirectories containing research artifacts.

Determine Integration Status

For each research subdirectory, read the non-README artifact files (product-brief.md, requirements.md, architecture.md, and any files in decisions/) and check their YAML frontmatter for integrated: true. An artifact is unintegrated if:

• The integrated field is absent (default state after research), OR
• The integrated field is present but not true

The README.md has no frontmatter and is not checked.

A research directory is "unintegrated" if any of its non-README artifact files are unintegrated.

Present Options

• No unintegrated research: "No unintegrated research found in docs/research/. Run /greenfield-start:research first."
• One directory: "I found unintegrated research for <subject>. Work with this one?"
• Multiple directories:

Unintegrated research available:

1. <dir-name> — <subject from README> (<N> artifacts)
2. <dir-name> — <subject from README> (<N> artifacts)

Which would you like to integrate?

After the user selects, load the research directory's README.md to understand available artifacts, confidence levels, and gaps.

Phase 2: Review Artifacts

Read each unintegrated artifact from the selected research directory and walk through them with the user.

Partial Integration

If some artifacts in the directory are already marked integrated: true from a previous run, skip them and only present unintegrated ones. Mention: "Some artifacts from this research were previously integrated. Showing only the remaining items."

Artifact Order

Present artifacts in this order:

1. product-brief.md — establishes what the thing is
2. requirements.md — the bulk of integrable content
3. architecture.md — system design (if present)
4. decisions/ — notable design choices (if present). Present decision records as a batch list with title and one-line summary each.

Adaptive Granularity

Start at section level. For each artifact, present content grouped by logical section:

Research for "<subject>" found these <area> features:

| ID | Requirement | Detail |
|---|---|---|
| ED-01 | Markdown editing | Full markdown support with live preview |
| ED-02 | Inline images | Drag-and-drop image embedding |
| ED-03 | Tag system | Nested hashtag organization |

Include these? (yes / no / let me pick individually)

Adaptive acceleration: If the user gives broad approvals ("yes", "include all"), shift to larger chunks or full artifacts.

Adaptive deceleration: If the user is selective ("yes to ED-01 and ED-03, skip ED-02"), maintain fine-grained presentation.

Output

Build a structured list of selected items organized by source artifact and section. Carry this forward to Phase 3.

Phase 3: Strategize

Read the current project documentation:

• docs/product-brief.md
• docs/requirements.md
• docs/roadmap.md
• docs/architecture.md
• docs/decisions/README.md

Map the selected research items to the project's existing structure and propose an integration strategy.

Strategy Presentation

Here's how I'd integrate the selected items into your project:

**Product Brief:**
- <what changes>

**Requirements:**
- <area> (<IDs>) → <component section>, <priority>, <phase>

**Architecture:**
- <what changes>

**Roadmap:**
- <what phases are updated>

**Decisions:**
- <which records to copy>

Does this strategy look right, or would you like to adjust anything?

Strategy Mapping Rules

• Requirement IDs: Re-map research IDs to the project's convention (component-prefix-based, matching existing patterns in docs/requirements.md).
• Priorities: Assign P0/P1/P2 based on how foundational the feature is.
• Roadmap placement: Place items into phases based on dependencies and the current phase structure.
• Empty templates: If project docs are mostly placeholder templates from init, propose an initial structure rather than trying to merge into nothing.
• Recontextualization: Research artifacts describe the researched product. Integrated content must describe the project's version — rewrite accordingly.
• Existing content conflicts: If project docs already contain overlapping content, note the overlap and propose reconciliation — append, replace, or flag for user decision.

Phase 4: Workshop

The user may accept the strategy or suggest modifications. Common adjustments:

• Changing priorities or phase placement
• Dropping items they selected in Phase 2
• Combining or splitting component sections
• Adjusting how conflicts are resolved

Revise and re-present the strategy until the user approves. This is a natural conversation — adapt to whatever the user says. When the user confirms, proceed to Phase 5.

Phase 5: Execute

Serialize the approved strategy into a structured dispatch prompt and dispatch the integration-executor agent.

Dispatch Prompt Structure

Include in the prompt:

1. Strategy: The full approved integration strategy with all mappings (component names, IDs, priorities, phases, conflict resolutions).
2. Selected content: The actual research text for each selected item — not just IDs, but the full content to integrate.
3. Project docs: The current content of each project doc that will be modified. Read each file and include its content so the subagent has the full context.
4. Research directory path: The path to the research directory (e.g., docs/research/2026-03-14-bear-note-taking-app/).
5. Research artifact paths: List of artifact file paths to mark as integrated after changes are applied.
6. Conventions: The project follows these conventions: kebab-case filenames, HTML comment placeholders (<!-- -->), progressive disclosure, no content duplication across files. Requirement IDs use short uppercase component prefixes. Decision records use YYYY-MM-DD-slug.md naming.

The subagent will work autonomously and produce changes to project docs.

Phase 6: Summary

After the subagent completes, present a summary of what was changed:

Integration complete.

**Files modified:**
- <path> — <what changed>

**Files created:**
- <path>

**Research marked as integrated:**
- <research dir path>

If the subagent reported any issues (missing target files, etc.), mention them in the summary.