Docs Ingest Public Private Grill Log

Initial Situation

docs-ingest-phase is already the public phase entrypoint for documentation ingest. Its current contract is strongest for implemented specs and project-maintenance documentation: it reads specs and implementation notes, writes routed flow and concept projections, updates Fumadocs navigation, marks source artifacts as ingested, and keeps root docs/ aligned.

The Harness wiki already separates several documentation surfaces:

• /docs/get-started for first-run CLI onboarding
• /docs/harness for Harness methodology, concepts, theory, flows, glossary, and docs-ingest output
• /docs/cli for CLI mechanics, scaffold lifecycle, manifests, baselines, and validation contracts
• /docs/project for internal project operations, specs, plans, implementation notes, maintenance logs, decisions, repo guidance, runbooks, and grill context

These routes are project examples, not standard page or section names that scaffolded repositories must copy.

The requested rework is to make docs-ingest-phase support public documentation more strongly while preserving the existing private technical documentation model.

Branch: Surface Model

Q1

Question: Should docs-ingest-phase model public/private documentation as audience intent, route topology, permission metadata, scaffold visibility, or all of them?

Accepted answer:

• Model public/private documentation through audience intent first, with route topology, permission metadata, and scaffold visibility as supporting signals.
• Public documentation is reader-facing product, usage, or domain documentation meant for users, adopters, or scaffold recipients.
• Private documentation is internal project, operator, maintenance, implementation, or planning documentation meant to preserve how the project is built and run.
• The current Harness routes such as /docs/get-started, /docs/harness, /docs/cli, and /docs/changelog are examples of this project's public-facing documentation surface, not sections that docs-ingest-phase should enforce across repos.
• The current /docs/project route is an example of this project's private documentation surface, not a universal route name that every repo must copy.
• Axiom: docs-ingest-phase must infer or use the target repo's domain-bounded docs architecture instead of hardcoding Harness Intelligence route names.

Branch: Public-Doc Authoring Pipeline

Q2

Question: Should public-facing documentation generation require the ordered writer flow writing fragments -> writing beats -> writing shape -> article/page, or should those writer steps be optional quality tools?

Accepted answer:

• Require the ordered writer flow for substantial new or rewritten public-facing documentation.
• The required order is:
  1. writing fragments
  2. writing beats
  3. writing shape
  4. final article/page
• Small public-doc patches may skip some or all writer stages when the change is narrow, such as typo fixes, tiny command corrections, metadata fixes, or changelog ledger updates.
• A skipped writer stage must be reported with an explicit no-op reason.
• Private technical ingest does not require the public writer flow unless the private material is being transformed into a reader-facing guide, concept page, usage page, or product/domain article.

Q3

Question: Where should the public writer flow plug into the existing docs-ingest-phase pipeline?

Accepted answer:

• The public writer flow plugs into docs-ingest-phase after source read/extraction and before routed public page writing or merging.
• It does not replace spec ingestion. Spec ingestion remains part of the existing private/project/domain ingest flow and should still happen when a spec or implementation notes need durable capture.
• When delivery-phase reaches docs-ingest-phase after substantial implementation changes, docs-ingest-phase should decide whether public-facing docs are affected.
• If substantial public-facing docs are created or materially updated, run writing fragments -> writing beats -> writing shape -> final article/page.
• If the change only requires private technical/project documentation, use the existing private ingest flow without the public writer stages.
• If the public-doc change is small or one-off, such as a typo, tiny command correction, metadata fix, or changelog ledger update, do not normally run the public writer flow; report the skipped writer stages as no-op reasons when relevant.
• Pipeline shape:
  1. resolve docs architecture
  2. classify target docs as public-facing, private technical, or both
  3. read source material
  4. run private spec/project ingest when required
  5. run the public writer flow when substantial public-facing docs are created or materially updated
  6. write or merge routed pages
  7. update route/navigation/bookkeeping

Q4

Question: Should public writer intermediates, such as fragments, beats, and shape, be persisted as durable files, temporary working notes, or only final page content?

Accepted answer:

• Persist the writer intermediates durably.
• writing fragments, writing beats, and writing shape outputs are valuable future context for public-doc passes, not disposable process notes.
• These artifacts should live in the private documentation part of the repo, not beside or inside the final public-facing docs unless the repo's docs architecture already defines a better private source area.
• The final public page remains the reader-facing output; the writer artifacts preserve editorial reasoning, source-backed claims, narrative sequencing, and chosen structure for future updates.
• Axiom: substantial public-doc creation or material update should leave both public final pages and private durable writer artifacts.

Q5

Question: How should durable public-doc writer artifacts be organized in the private docs surface?

Accepted answer:

• Organize durable public-doc writer artifacts as one private artifact bundle per public-doc target or substantial docs pass.
• Default bundle shape:
  • fragments.md
  • beats.md
  • shape.md
• The bundle should be keyed by the public-doc topic, target page slug, or substantial docs pass slug.
• In a routed private docs architecture like this repo, the default location should be a private docs/project area such as apps/wiki/content/docs/project/public-docs/<topic-or-page-slug>/.
• Other repositories may use their own equivalent private docs location; docs-ingest-phase must adapt to the repo's docs architecture.
• Avoid a single global fragments/beats/shape file because it creates merge noise and makes future targeted passes harder to recover.
• Avoid placing writer artifacts beside final public pages unless the repo's architecture explicitly treats that location as private source material.

Q6

Question: Should durable public-doc writer artifacts be routed human-facing private pages, hidden/source-only files, or configurable per repo?

Accepted answer:

• Use routed human-facing private pages when the repo has a routed private docs surface.
• Use source-only private files as a fallback when the repo does not have routed private docs.
• In this repo, the natural location is under the private project docs surface, such as apps/wiki/content/docs/project/public-docs/<topic-or-page-slug>/, with normal meta.json navigation.
• Do not enforce a universal docs/public-docs prefix across user repos.
• docs-ingest-phase should discover or follow the target repo's docs architecture and place writer artifacts in the repo's private documentation area.
• A fallback path may be suggested only when no private docs convention exists, and it must be described as a fallback, not a standard.
• Axiom: writer artifacts must be discoverable to future docs-ingest runs, but the path is repo-bounded.

Q7

Question: Should the final public pages link back to their private writer artifacts, should private writer artifacts link forward to final public pages, or both?

Accepted answer:

• Private writer artifacts should link forward to their final public pages.
• Final public pages should not visibly link back to private writer artifacts by default.
• Public pages should stay reader-facing and clean.
• Private writer artifacts should preserve traceability fields such as target public page path, source spec/change/run, artifact chain, and last updated date.
• Public pages may keep non-visible source/frontmatter metadata when useful and compatible with the repo's docs system.

Q8

Question: Should writing fragments, writing beats, and writing shape be separate reusable skills that docs-ingest-phase orchestrates, or internal sections inside the docs-ingest skill?

Accepted answer:

• They are separate reusable skills.
• docs-ingest-phase orchestrates them when substantial public-facing docs are created or materially updated.
• The skills are writing primitives, not docs-ingest-specific mechanics.
• Source the skills from Matt Pocock's skills/in-progress repository, then adopt them in /Users/stefan/Desktop/repos/wearedevpunks-skills as the shared source of truth.
• Sync adopted shared skills back into this repo's distributed apps/cli/skills tree.

Q9

Question: Should writing-fragments, writing-beats, and writing-shape be included in the default distributed docs skill pack?

Accepted answer:

• Include them in the default docs pack with docs-ingest-phase.
• Rationale: public-doc authoring is part of the default Harness docs workflow, not a rare optional stack-specific capability.
• The default docs pack should include:
  • docs-ingest-phase
  • writing-fragments
  • writing-beats
  • writing-shape
• The phase remains the orchestrator. The writing skills remain direct reusable tools for standalone writing sessions.

Q10

Question: What remains unresolved before turning this grill into an implementation spec or backlog item?

Accepted answer:

• The requirements design is closed enough for implementation.
• Implementation has already started in this session:
  • the three writing skills were adopted from Matt Pocock's MIT-licensed skills/in-progress source
  • the shared skills source repo was updated first
  • Harness's distributed apps/cli/skills mirror was updated locally
  • the default docs pack now includes docs-ingest-phase, writing-fragments, writing-beats, and writing-shape
  • docs-ingest-phase now documents the public-doc writer flow and private durable writer artifacts
• Remaining rollout validation:
  • publish or otherwise sync the shared skills repo changes so the literal bun run sync:skills path can pull them from the public remote
  • run bun run sync:skills after the shared repo is published, or keep the current local mirror as the implementation evidence until publish

Q11

Question: Should publishing/syncing the shared skills repo be part of this same scope before the grill is considered fully closed, or a follow-up rollout task?

Accepted answer:

• Keep publishing and syncing in the same scope.
• Shared skills were committed and pushed to wearedevpunks/skills on main at f60f2a21299a58aa5cd7a98bcf78ffb016c77d1b.
• Harness then ran the real bun run sync:skills path, which synced from the public remote into apps/cli/skills.
• Sync metadata in apps/cli/.devpunks-cache/skills-sync.json records commit f60f2a21299a58aa5cd7a98bcf78ffb016c77d1b.
• The Skill/source-of-truth rollout branch is closed.