Ingest-docs synthesizer: consolidate 60+ documents of planning in coherent context

When you enter a mature brownfield, the planning documentation is typically scattered: last year's public roadmap, old ADRs, decisions in commit messages, RFCs in the wiki. Without consolidation, GSD starts from a fragmented context and produces plans that do not respect already made decisions. The command /gsd:ingest-docs exists exactly for this: Simplify N documents scattered across PROJECT.md + REQUIREMENTS.md + ROADMAP.md consistent.

Independence Disclaimer: I am not affiliated with XPHX0XPHX or XPHX1XPHX. I used ingest-docs on the Brownfield Portfolio for Q2 2026 to consolidate ~60 scattered planning documents. docs/05_strategy/02_roadmap/ master plan 08_piano_master_2026.md.

The problem: scattered documents in a brownfield area.

A living project for 2-3 years has been accumulating planning documents in various locations:

• Architecture Decision Records in docs/adrs/
• Public Roadmap docs/strategy/
• Internal RFCs in wiki or Notion
• Decisions in long commit messages
• Issue tracker (Jira / GitHub) closed with reasons
• Documents Word/PDF from meeting strategy

Without consolidation, GSD will not know that the decision X was already taken in 2024 and you'll have to start the discussion all over again. Worse, take an opposite decision without noticing.

What does /gsd:ingest-docs do?

Create a sub-agent gsd-doc-classifier for each document identified, then a gsd-doc-synthesizer aggregates the output. Typical workflow: 1. XPHX0XPHX 2. aggruppa i 3. output. Flusso di lavoro tipico: 4. Aggregates the 5. Output. Typical workflow: 6. XPHX1XPHX

1. Find all markdown under the specified path indicated (default: docs/**/*.md).
2. For everyone, Classifier extracts: type Specification Document Title, Scope Summary, cross-references, Status, decisions.
3. Synthesizer aggregates N classification JSON in a single context.
4. Apply rules of precedence (most recent date wins at parity of authority; locked decision explicitly wins over tentative decision).
5. Produce summary in PROJECT.md (Core values + closed decisions) REQUIREMENTS.md (Request IDs categorized) + ROADMAP.md Phases if interpretable.
6. Produce INGEST-CONFLICTS.md With 3 buckets of issues to resolve.

Three buckets of INGEST-CONFLICTS.md

The main output for debugging consolidation is the file conflicts:

1. I'm not seeing any Italian text to translate. Please provide the text you'd like me to translate, and I'll be happy to assist you.Conflicts are automatically resolved by priority rules. Example: two ADRs on the same topic, ADR-2024-12 and ADR-2026-03 - the most recent one wins. Audit list, no action required.
2. Competing VariantsEquivalence of authority, not resolvable automatically. Example: ADR-2025-07 says "use PostgreSQL", ADR-2025-09 says "use MongoDB" (same quarter, same author). Escalation user: choose which one is binding.
3. Unresolved blockersDecisions are LOCKED in conflict. Direct. Example: PROJECT.md declares "stack Java", REQUIREMENTS declares REQ with "implement in Python". Hard-block: GSD refuses to proceed without explicit user decision.

Real example: consolidation master plan portfolio

On my portfolio I used ingest-docs to produce 08_piano_master_2026.md from 60+ planning documents scattered across docs/05_strategy/02_roadmap/ (Outdated roadmaps, decisions taken between 2024 and 2026, plans for thematic pillars, etc.). Result: Synthesis:

• One thousand three hundred and twenty-nine lines of consolidated master plan.
• 18 foundational principles A-R Identified as strategic pillars.
• 13 auto-resolved conflicts Subsequent versions of policy that exceeded previous ones.
• 4 competing variantsSelection of recurring consulting services vs spot, VAT threshold, freelance EU vs USA, breakdown of monetization tiers.
• 0 unresolved blockersExisting planning coherent in decision-making is LOCKED.

Total time spent: ~3 hours (running the classifier for 60 parallel documents, then synthesizer). Without ingestion I would have spent days of manual reading to recreate the same coherence.

Rules of precedence built-in

The synthesizer applies rules in order:

1. I'm ready to translate. Please provide the Italian text.Superseded / rejected / deprecated → discarded. Proposed → caution. Accepted → considered.
2. DataAt equal status, the most recent one wins.
3. DisclosureDecision is marked as either "LOCKED" or "BINDING", winning over a tentative or exploratory decision.
4. AuthorityApplication Development Rules > Design Document > Commit Message > Issue Comment.
5. SpecificityDecision on a specific scope wins over decision on a general scope for that scope.

If two decisions pass through all levels at parity, they end up in competing variants (user escalation).

Pattern: ingest newspaper for audit

On my portfolio I also use ingest-docs outside of the onboarding context, as quarterly magazine:

1. Launch ignition on docs/**/*.md + .planning/phases/*/[A-Z]*.md.
2. Compare new summary with the current PROJECT.md file.
3. Diff = new decisions (committed to docs but not reflected in PROJECT) + old decisions superseded.
4. Update PROJECT.md.

The quarterly audit captures decisions taken "on the fly" in the documents but never formalized in the master state.

Anti-pattern: ingest on unstructured documents

Ingest-docs functions well with Markdown using a recognizable structure (ADR with frontmatter, PRD with standard headers, design doc with explicit sections). It does not function well on: XPHX0XPHX

• The stream-of-consciousness markdown has no structure. The classifier produces vague synthesis, the synthesizer doesn't know what a decision is versus what a note is.
• Historical documents with an expositional style (e.g. "Once upon a time we decided X but then in 2024 we changed to Y because..."). It is difficult to extract the canonical decision.
• Slide deck converted to markdown (bullet points without context). Missing rationale and references.

Mitigation: pre-processing pre-ingestion. Format informal docs into an ADR-like skeleton with explicit sections (decision, status, context, consequences) before ingestion.

Ingest by cluster thematic pattern

On large document bases (100+ files), instead of a global ingestion, ingestion by thematic cluster:

1. I don't see any Italian text provided. Please provide the Italian text you'd like me to translate, and I'll be happy to assist you. docs/security/**/*.md Summary security in Project Section Security.
2. I don't see any Italian text provided. Please provide the Italian text you'd like me to translate, and I'll be happy to assist you. docs/i18n/**/*.md → localization summary in PROJECT §localization.
3. I don't see any Italian text provided. Please provide the Italian text you'd like me to translate, and I'll be happy to assist you. docs/deploy/**/*.md Summary deployment in PROJECT Deploy Section.

Cluster maintains a low-context window, more accurate classifier because it has disambiguated topics. Trade-off: cross-cluster references need to be managed manually (e.g., security decisions that impact deployment).

When NOT to use ingest-docs

1. Progetto GreenfieldNothing to consolidate. Start with /gsd:new-project directly
2. Brownfield with consolidated documents already.If you have docs/00-master.md Coherent, it would produce duplication Without value.
3. Unconvertible proprietary format documentsIf your docbase is in a format that cannot be easily converted to Markdown, do not ingest it. Spend time converting it first.

Typical session: Ingest Brownfield

Workflow: 1. XPHX0XPHX 2. Process 3. Initiate 4. XPHX1XPHX 5. Task 6. Assign 7. Execute 8. Monitor 9. Complete 10. Review 11. XPHX0XPHX

1. Identify paths to consolidate documents (e.g. docs/strategy/ + docs/adrs/).
2. Verify documents are in Markdown. Convert non-Markdown using pandoc/jq.
3. Lancia /gsd:ingest-docs docs/strategy/ docs/adrs/.
4. Wait for parallel classifiers to spawn (N documents in parallel, Sonnet).
5. The synthesizer produces PROJECT.md draft and REQUIREMENTS.md draft and INGEST-CONFlicts.md.
6. Update INGEST-CONFLICTS.md: resolve competing variants and unresolved blockers.
7. Approve XPHX0XPHX XPHX1XPHX as canonical.

Time for a docbase of 60 files: 2-3 hours wall clock. Without ingestion: days of manual consolidation.

What I learned writing this article

The thing that struck me most was how fragmentary My own planning documentation before ingestion. I thought I had "had it in mind"; ingestion revealed 13 self-resolving conflicts (superseded decisions that I had never marked) + 4 competing-variants true. The synthesis required 3 hours; without it, I would have continued to plan on an inconsistent basis.

Second insight: ingest-docs is an instrument of discipline, not just consolidation. Knowing that every quarter you will pass your docs through ingest pushes you to write more structured ADRs, make decisions with explicit status, and trackable rationale. The fact that the tool exists improves the upstream docbase.

Avoided pattern

• No preprocessing requiredUnstructured documents produce vague summaries. Invest 30 minutes to reformat the 5-10 critical documents in ADR-like before ingestion.
• Skip INGEST-CONFLICTS.mdThe file is where true decisions live. Skipping it means losing the value of consolidation.

A story worth sharing

Placeholder Section If you have used ingest-docs on complex docbase, write to me federico@federicocalo.dev.

Previous cluster: Wave-based parallel execution Next cluster: Auto-curated memory management →