Harness Wiki Refactor Grill Log

This log records accepted decisions for the Harness wiki refactor around lifecycle flows, skill-pack guidance, and individual skill lookup.

Context

Initial issue: the current Harness wiki structure is technically complete but feels dispersed. Lifecycle/how-to material sits too low in the sidebar, the skill-pack page explains the model but does not help operators find individual skills, and phase-wrapper behavior needs to be clearer inside the supported usage flows.

Initial source evidence:

• apps/wiki/content/docs/harness/meta.json currently orders lifecycle-flows after trust-and-adoption.
• apps/wiki/content/docs/harness/lifecycle-flows/ already has routed flow pages, but the set is broad and not organized around the main operator-supported flows.
• apps/wiki/content/docs/harness/skills-and-packs/skill-packs.mdx explicitly says the section is not a catalog, which conflicts with the requested need for brief individual skill guidance and source links.
• Shared skill source of truth is /Users/stefan/Desktop/repos/wearedevpunks-skills; routed wiki changes should link to GitHub viewer paths for those source SKILL.md files.

Branch: Information Architecture

Q1

Question: Should Lifecycle Flows move directly after Foundations in the Harness sidebar, before Prompt Surfaces and Skills/Packs?

Accepted answer:

• Yes. Move Lifecycle Flows directly after Foundations in the Harness sidebar so the how-to material appears before deeper model/reference sections.
• Preserve the routed wiki architecture and existing lifecycle folder unless a later writing decision proves a rename is worth the route churn.

Branch: Supported Flow Naming

Q2

Question: Should the reader-facing section language say Supported Flows or How To Use Harness?

Accepted answer:

• Use Supported Flows as the reader-facing language.
• Keep the existing lifecycle-flows route/folder name unless route churn becomes necessary later.
• Avoid "How To Use Harness" as the primary label because it reads like onboarding copy instead of technical methodology.

Branch: Supported Flow Set

Q3

Question: Should the lifecycle section be reorganized around four primary supported flows, with existing adoption/update/docs pages kept as supporting flows?

Accepted answer:

• No. Do not frame the section as four primary flows plus lesser supporting flows.
• Harness supports more than those four flows, and the other flows are not less important.
• The section should make each supported flow legible by the value it provides and the end goal it achieves: what the flow is there for, when to use it, and what terminal outcome it produces.

Q4

Question: Should each Supported Flow page open with a consistent value/outcome block?

Accepted answer:

• Yes. Give each flow a consistent opening lens:
  • Use this when...
  • It gives you...
  • It ends with...
  • Wrapped phase/skills...
• Use the block to explain the job of each flow without ranking it against the others.

Branch: Skill Guidance

Q5

Question: Should individual skill guidance live as a compact lookup section inside skill-packs.mdx, or as a separate routed page under Skills and Packs?

Accepted answer:

• Create a separate routed page under Skills and Packs, likely skill-reference.mdx.
• Keep skill-packs.mdx focused on pack resolution, pack types, and pack output.
• The reference page should group skills by default pack, give one-line purpose per skill, and link to the shared source SKILL.md.
• Use the local source remote as the link base unless contradicted by GitHub: https://github.com/wearedevpunks/skills/blob/main/.

Q6

Question: Should the skill reference list only default/agnostic/phase skills, or also include framework and language skills?

Accepted answer:

• Extend the skill reference beyond default/agnostic/phase skills.
• Cover the shared skill library as a whole, including framework and language packs.
• Keep it grouped and terse so the page stays a usable reference rather than an undifferentiated catalog dump.

Q7

Question: What should each skill-reference entry contain?

Accepted answer:

• Use a terse table entry shape:
  • Skill
  • Use when
  • Pack/category
  • Source
• Keep Use when focused on the value or trigger for invoking the skill.
• Avoid longer output/provides columns by default; add notes only where a skill needs a caveat.

Branch: Repository Knowledge Flow

Q8

Question: In the requirements flow, should "creating a repository graph" mean a durable repository knowledge map that feeds requirements/backlog, rather than a code dependency graph or backoffice project graph?

Accepted answer:

• The intended meaning is project knowledge and context persisted in backlog.
• Do not use "repository graph" as the canonical wiki term because it collides with code dependency graphs and backoffice project graphs.
• The requirements flow should explain how $requirements-phase captures project knowledge, context, decisions, glossary, parked scope, and accepted branches into backlog structure so future delivery can work from pinned context.

Branch: Flow Placement

Q9

Question: Should adopt-repository and scaffold-setup-and-prompt-handoff stay under Harness Lifecycle Flows?

Accepted answer:

• No. They feel out of place in Lifecycle Flows because they are CLI onboarding/setup usage, not phase-wrapper supported flows.
• Move their substance into get-started/basic-usage and/or the CLI scaffold lifecycle pages.
• Improve wording at the new location so adoption/setup still explain what value they provide, but do not present them beside phase-invocation flows.

Q10

Question: After moving adoption/setup out, should Lifecycle Flows start with requirements-to-backlog?

Accepted answer:

• Yes. Start the Harness supported-flow section with requirements-to-backlog.
• Proposed remaining order:
  1. requirements-to-backlog
  2. manual-delivery-flow
  3. afk-phase-delivery-flow
  4. debug-with-runtime-evidence
  5. clawpatch-bug-lifecycle
  6. maintain-wiki-after-implementation
  7. baseline-update-and-feedback
• This makes CLI setup/adoption live in Get Started or CLI docs, while Harness Lifecycle Flows start where phase/workflow usage begins.

Q11

Question: Should baseline-update-and-feedback remain in Harness Lifecycle Flows, or move to CLI/update docs with a Harness link-out?

Accepted answer:

• Move it out of Harness Lifecycle Flows.
• Treat dp update as a Command Capability in Basic Usage and CLI update docs.
• Keep a short Harness-facing feedback-loop mention or link from Trust/Adoption or Validation/Tools so the value is preserved without keeping command mechanics in the skill-flow section.
• Lifecycle Flows should become the skill-flow and hybrid-flow area.

Q18

Question: After moving adoption/setup/baseline command flows out, what should the Lifecycle Flows order be?

Accepted answer:

• Final Lifecycle Flows order:
  1. requirements-to-backlog
  2. manual-delivery-flow
  3. afk-phase-delivery-flow
  4. debug-with-runtime-evidence
  5. a dedicated review flow page, likely review-current-branch
  6. clawpatch-bug-lifecycle
  7. maintain-wiki-after-implementation
• Add a dedicated review flow page because $review-phase is an explicitly supported flow, not only an inner delivery gate.
• Remove or relocate command-oriented lifecycle pages: adopt-repository, scaffold-setup-and-prompt-handoff, and baseline-update-and-feedback.

Q19

Question: Should the new review page be titled Review Current Branch?

Accepted answer:

• Yes. Use Review Current Branch as the operator-facing title.
• The page should explain the flow for analyzing, improving, refactoring, and de-slopifying the current branch before merge.
• The page should still make $review-phase the powered-by phase wrapper.

Branch: Grill Continuation

Q20

Question: Should grilling stop now and move into writing/implementation?

Accepted answer:

• No. Continue grilling until the usage overview, diagram model, capability classification, page relocation semantics, and writing shape are pinned.
• The implementation checklist is useful, but not enough to replace remaining requirements decisions.

Q21

Question: What should the Basic Usage diagram optimize for?

Accepted answer:

• Use a Mermaid diagram that communicates state transitions and actor interactions, not every internal detail.
• Prefer the runtime sequence-diagram aesthetic: explicit participants and message arrows.
• Adapt the sequence style to this use case with participants such as Operator, dp CLI, Backlog Provider, Follow-up Agent, Managed Harness Files, and Supported Flows.
• The diagram should still answer the overview questions: which macro command runs, where the human interacts, what is automatic/tool-backed, how backlog context maps to EPIC and child stories/sub-issues, and where the post-setup handoff lands.
• Avoid turning the diagram into a full implementation trace.

Q22

Question: Should Basic Usage include a small capability table after the diagram?

Accepted answer:

• Yes. Add a capability table after the diagram.
• Use columns: Capability, Type, Who drives it, What it produces.
• The table should classify command capabilities, skill flows, and hybrid flows.
• External tools should be shown as dependencies inside those rows, not as standalone capability rows.
• Keep it as an overview table, not a full skill catalog.

Q23

Question: What rows should the Basic Usage capability table include?

Accepted answer:

• Include these overview rows:
  • dp scaffold init | Command | Operator + CLI | requirements/wiki seed and next prompt
  • $requirements-phase | Skill flow | Agent + operator | project context persisted into EPIC and child stories/sub-issues
  • dp scaffold setup | Command | Operator + CLI | repo scan, pack selection, managed files, manifest, and handoff
  • $delivery-phase | Skill flow | Agent | spec, plan, implementation, review, validation, and docs closeout
  • $debugging-phase | Skill flow | Agent + runtime evidence | proven cause, bounded fix, and rerun proof
  • $review-phase | Skill flow | Agent | findings, risks, simplification/refactor guidance
  • ClawPatch lifecycle | Hybrid | Agent + ClawPatch | discovered, selected, and resolved findings
  • $docs-ingest-phase | Skill flow | Agent | routed wiki/project docs and repo-docs alignment after proven changes
  • dp update | Command | Operator + CLI | scaffold drift check or managed update
  • dp report | Command | Operator + CLI | Harness/tooling/docs friction issue for triage
• Mention tool/provider dependencies inside relevant rows or supporting prose: Linear/GitHub for backlog, ClawPatch for bug lifecycle, agent-browser for browser evidence, opensrc for source inspection, portless for local URLs.

Branch: Usage Overview

Q12

Question: Should the Get Started / Basic Usage area gain a stronger overview that explains the two macro commands and the full workflow before the deeper pages?

Accepted answer:

• Yes. The current docs mention the concepts, but they are too buried and do not carry enough weight for a first reader asking "so now what?"
• Add or strengthen a base-usage overview that explains dp scaffold init and dp scaffold setup very simply.
• The overview should make the post-setup agent handoff explicit as the next state after setup.
• The overview should show where operator interaction is required and where automatic steps rely on external tools.

Q13

Question: Should the overview include a diagram?

Accepted answer:

• Yes. Use Mermaid diagrams for the workflow.
• The diagram should make the two macro commands, backlog interaction, handoff, skill flows, automatic checks, and external tools visible without requiring the reader to infer the process from prose.

Q14

Question: Should backlog guidance be more prominent in both the init/basic-usage material and the requirements/backlog flow?

Accepted answer:

• Yes. Explain the provider-agnostic backlog model directly: whether the provider is Linear or GitHub, Harness maps accepted project context into an EPIC and breaks it down into child stories/sub-issues.
• dp scaffold init should be framed as preparing the requirements/backlog surface when the project still needs pinned context.
• Requirements flow pages should explain the EPIC -> breakdown relationship as the bridge from project context to later delivery.

Q15

Question: Should the wiki classify Harness capabilities by command, skill flow, and external tool?

Accepted answer:

• Yes. Use this classification to clarify what the operator invokes directly, what the agent runs as a skill/phase flow, and which flows depend on external tools.
• Commands are CLI entrypoints such as dp scaffold init, dp scaffold setup, dp update, and dp report.
• Skill flows are phase or workflow invocations such as $requirements-phase, $delivery-phase, $debugging-phase, $review-phase, $docs-ingest-phase, and related inner skills.
• External tools are dependencies inside command, skill-flow, or hybrid rows, not standalone primary capabilities.
• Hybrid flows, especially ClawPatch, should be labeled as hybrid rather than forced into only one bucket.

Q16

Question: Where should the new usage overview live?

Accepted answer:

• Expand apps/wiki/content/docs/get-started/basic-usage.mdx.
• Do not create a new page for this overview.
• Introduction remains the entry, Basic Usage becomes the command and workflow overview, and deeper CLI/Harness pages stay linked from there.

Branch: Final Closure

Q24

Question: What is the final grouping for skill-reference.mdx?

Accepted answer:

• Group by the shared skill repository taxonomy:
  1. Phase wrappers and lifecycle helpers
  2. Agnostic requirements, planning, research, quality, debug, backend, frontend, subagent, CLI, and skill-authoring skills
  3. Framework packs
  4. Language packs
• Within each group, use tables with Skill, Use when, Pack/category, and Source.
• Keep one-line Use when copy. Add short notes only for important caveats, such as goalify being a prompt compiler rather than a phase even though it lives under skills/phases.

Q25

Question: What is the final writing shape for the wiki refactor?

Accepted answer:

• Preserve existing routed MDX style: terse frontmatter, direct opening, short sections, tables where parallel rows repeat, Mermaid for workflow overview, and existing page architecture.
• Expand get-started/basic-usage.mdx first because it answers the first-run "so now what?" question.
• Move command-oriented lifecycle content out of Harness Lifecycle Flows by merging useful adoption/setup/update wording into Get Started and CLI pages rather than deleting the concepts.
• Reorder harness/lifecycle-flows around skill-flow and hybrid-flow usage.
• Add review-current-branch.mdx.
• Add skills-and-packs/skill-reference.mdx and link to it from skill-packs.mdx and section metadata.
• Revise existing supported-flow pages with the agreed value/outcome block.

Q26

Question: Are all grill branches closed enough for writing and implementation?

Accepted answer:

• Yes. All active branches are closed.
• Remaining work is writing, page relocation, route metadata, and validation, not requirements discovery.

Branch: Entrypoint Architecture Continuation

Q27

Question: Should the public Harness wiki section currently labeled Supported Flows be refocused around available Harness entrypoints instead of only phase/lifecycle flows?

Accepted answer:

• Yes. The section should explain the available entrypoints: what Harness Intelligence can actually do.
• Keep Get Started as-is for now.
• Remove /docs and /adopt shortcuts from the sidebar.
• Move Foundations below the entrypoint section and make it carry more theory signal.
• Add an overview/index page that explains each broad entrypoint category.
• Include more than phase flows: atomic skills such as parallel-research and handoff also need first-class treatment.

Q28

Question: Which existing pages should be consolidated, retitled, nested, or made more discoverable?

Accepted answer:

• Merge /trust-and-adoption into a single page.
• Make /validation-and-tools more discoverable through stronger links from other pages.
• Rename Requirements To Backlog toward brainstorming, requirements, and backlog definition.
• Treat Manual Delivery Flow as the main implementation entrypoint.
• Treat AFK Phase Delivery Flow as a variant nested under the main delivery flow.
• Retitle debugging, review, ClawPatch, and docs maintenance pages around clearer user intent: debugging, review, massive bug hunt and fixing, and docs update.
• When a page mentions a tool, link to the tool's page when the wiki has one.
• When a page mentions a skill, link to its source page in the wearedevpunks/skills GitHub repository.