Wiki Onboarding Skill Grill Log

Initial Situation

dp scaffold init currently seeds the requirements gate, backlog-writing skill, and routed wiki root for a project. It pins the backlog provider and wiki framework, then prints an operator prompt that tells the next agent to inspect and reconcile the generated output before starting requirements discovery.

Existing-project adoption has a missing-context problem: Harness can create the wiki structure, but it cannot recover the project history that would normally exist as scopes, plans, specs, implementation notes, and decision records. The strongest recoverable starting point is a source-backed map of current product and code behavior, then a developer interview that challenges that map before it becomes durable wiki knowledge.

Issue

The team needs to decide whether scaffold init should remain a lightweight preparation step or become the entrypoint for a repo-onboarding workflow that audits the existing codebase, derives functional and UX flows, runs a requirements grill against the developer, and writes initial wiki/spec context.

The hard boundary is evidence quality. The workflow can derive observed behavior from code and docs, and it can grill the developer into accepted requirements. It cannot honestly invent implementation notes, historical rationale, or tech-debt provenance that the repo does not contain.

Solution Direction Under Grill

Introduce a Docs onboarding skill that is scaffolded by dp scaffold init and then activated immediately by the generated post-command prompt. init should provide the proper wiki root and common handoff. The skill should inspect the codebase, existing repo docs, and backlog context, then convert existing knowledge into structured wiki docs. It should feed inferred requirements and contradictions into requirements-grill so the developer can confirm, correct, reject, or park them. After the grill closes, the skill should automatically call create-spec so the accepted onboarding artifacts are structured into proper spec artifacts and the project gets an evidence-backed reconstructed spec history. Historical implementation notes and tech-debt records remain absent unless backed by existing evidence.

Branch: Init Contract

Q1

Question: Should onboarding run automatically as part of dp scaffold init, or should init only scaffold a dormant onboarding skill for later use?

Accepted answer:

• dp scaffold init must scaffold the Docs Onboarding Skill and print a post-command prompt that tells the continuing agent to activate that skill immediately and start onboarding the wiki.
• The common init output is the activation prompt. It must not frame onboarding as optional future work.
• The skill still owns the actual repo analysis, developer Q&A, and wiki/spec output. The CLI prepares the skill and handoff; the agent executes the onboarding workflow from the prompt.

Q2

Question: Should the skill id be docs-onboarding, and should dp scaffold init print a direct activation prompt?

Accepted answer:

• Yes. The skill id should be docs-onboarding.
• dp scaffold init should print a direct, imperative activation prompt that tells the continuing agent to activate $docs-onboarding immediately.
• Prompt shape:

Activate $docs-onboarding now. Inspect the codebase, existing docs, and the selected backlog provider. Build the project map, run the targeted requirements grill, then call create-spec to reconstruct evidence-backed specs into the scaffolded wiki.

• The prompt must not frame Docs onboarding as optional future advice.

Glossary Q3

Question: What is the canonical name for the new onboarding skill?

Accepted answer:

• Canonical term: Docs Onboarding Skill — A reusable Harness skill that turns an existing repository into initial wiki-ready project context through source-backed discovery and developer grilling.
• Avoid: wiki onboarding skill, scaffold init magic.
• Relationship: Docs Onboarding Skill onboards the project wiki after dp scaffold init.

Branch: Discovery Inputs

Q3

Question: Should the Docs Onboarding Skill start by reconciling the wiki root, or assume dp scaffold init provided the proper wiki and focus on existing project knowledge?

Accepted answer:

• dp scaffold init owns providing the proper wiki root and common output prompt.
• The Docs Onboarding Skill should assume that wiki exists, then inspect both the codebase and existing repo docs to figure out how to convert existing knowledge into structured wiki docs.
• The skill should still notice obvious contradictions between the generated wiki location and the repo layout, but wiki-root creation/reconciliation is not its primary responsibility.

Q4

Question: Should the Docs Onboarding Skill inspect backlog context during onboarding?

Accepted answer:

• Yes. Because dp scaffold init explicitly asks for the backlog provider, the Docs Onboarding Skill must look for existing backlog context as part of onboarding.
• If the skill cannot find the backlog, it must ask the developer where the backlog exists before treating the project as having no backlog.
• Backlog discovery is input gathering for requirements and specs; automatic backlog mutation remains out of scope until later backlog-writing decisions are closed.

Q5

Question: What should count as "backlog found" during Docs onboarding?

Accepted answer:

• Use the pinned provider file from dp scaffold init to identify the expected backlog provider.
• Probe the remote backlog provider API first when the required connector/tool/auth is available.
• Then inspect local backlog clues: existing specs, issue matrices, backlog markdown, project docs, or .devpunks metadata.
• Remote backlog evidence and local backlog clues are both mandatory and equally important discovery lanes.
• If remote provider access or local backlog clues cannot be found, ask the developer where the backlog exists or how to access it before assuming the project has no backlog.

Branch: Codebase Discovery Scope

Q13

Question: What must the Project Map contain before the onboarding grill starts?

Accepted answer:

• Feature and UX flows.
• Operator/developer workflows and commands.
• App, package, and code paths for each flow.
• Docs and backlog sources for each flow.
• Integrations and data boundaries.
• Contradictions and missing evidence.
• Candidate spec groupings.
• The Project Map should be concrete enough for the grill to challenge real project behavior and for create-spec to reconstruct specs without turning onboarding into a vague repo tour.

Q14

Question: How deep should codebase discovery go?

Accepted answer:

• Inspect entrypoints, routes/pages, commands, API handlers, schemas/models, tests, config/env examples, and existing docs.
• Do not deep-read every implementation file by default.
• Deep-read implementation files only when needed to explain a flow, resolve a contradiction, or map a data boundary.
• This keeps onboarding bounded while still source-backing the Project Map.

Branch: Backlog And Spec Boundary

Q6

Question: Should Docs onboarding stop at confirmed spec seeds, or automatically call create-spec after the grill closes?

Accepted answer:

• After the onboarding grill closes, the Docs Onboarding Skill must automatically call create-spec.
• create-spec owns properly structuring the accepted onboarding artifacts into spec artifacts.
• The goal is to reconstruct the project spec history from code, existing docs, backlog context, and accepted grill decisions.
• Reconstructed spec history must stay evidence-backed. The workflow can reconstruct current-state and accepted historical/spec context from source evidence, but it must not invent implementation notes, rationale, or tech-debt history without supporting artifacts.

Q7

Question: How should create-spec group reconstructed specs after Docs onboarding?

Accepted answer:

• Group reconstructed specs by backlog epic when backlog context exists.
• If no backlog epic is available, group by user-facing feature flow.
• Use app/package boundaries only as supporting evidence, not as the primary grouping rule.
• The grouping should preserve product intent and avoid turning implementation structure into fragmented spec history.

Q8

Question: What evidence labels should reconstructed specs carry?

Accepted answer:

• Each reconstructed spec must carry an Evidence Level.
• Confirmed: code, docs, or backlog evidence exists and the developer confirmed the reconstructed requirement.
• Inferred: strong code, docs, or backlog evidence exists, but developer confirmation is still missing.
• Contradicted: source evidence conflicts and needs resolution before the spec can be trusted.
• Missing: expected context was not found, and the spec must ask a follow-up.
• This label set is accepted as the initial rule and may be revisited if implementation shows it is too coarse or too noisy.

Q9

Question: Where should Evidence Level live in the reconstructed spec?

Accepted answer:

• Put Evidence Level in both spec frontmatter and a short body section.
• Frontmatter makes reconstructed specs queryable by future agents and tooling.
• The body section gives humans a concise evidence summary with links to code, docs, backlog, or grill decisions.
• This is an implementation-detail default, not a product-level decision to keep re-grilling.

Branch: Developer Grill Loop

Q10

Question: How aggressive should the developer grill be before create-spec runs?

Accepted answer:

• The onboarding grill should be targeted, not exhaustive.
• It must grill contradictions, missing backlog location, unclear feature ownership, and high-impact inferred requirements before create-spec runs.
• Low-risk current-state facts can flow into create-spec as Inferred instead of blocking on developer confirmation.
• The goal is useful reconstructed specs without turning onboarding into a long open-ended interview.

Q11

Question: Should Docs onboarding be resumable by default?

Accepted answer:

• Yes. Docs onboarding must be resumable by default.
• Before asking developer questions, the skill should persist the project map and grill status so an interrupted onboarding can resume without rescanning from zero.
• Resume should continue from the saved discovery/grill state, then proceed to create-spec after the targeted grill closes.

Q12

Question: Should the skill auto-pin obvious low-risk current-state facts as Confirmed, or keep them as Inferred unless the developer explicitly confirms?

Accepted answer:

• Keep low-risk current-state facts as Inferred unless the developer explicitly confirms them or unambiguous docs/backlog intent backs them.
• Code-only evidence can prove observed behavior, but it does not prove intended requirement status.
• Confirmed means human-confirmed or backed by unambiguous requirement intent from backlog/docs.
• The skill may autonomously carry low-risk facts into create-spec as Inferred without grilling them.
• The skill should autonomously close the Developer Grill Loop when every blocking contradiction, missing backlog location, unclear feature owner, and high-impact inferred requirement is either confirmed, rejected, parked, or marked Missing with a follow-up.

Branch: Wiki Output Model

Q15

Question: Which wiki artifacts should Docs onboarding write before create-spec runs?

Accepted answer:

• Write onboarding artifacts under content/docs/project/onboarding/.
• Required onboarding artifacts:
  • project-map.md
  • onboarding-grill-status.md
  • onboarding-grill-log.md
• create-spec then writes reconstructed specs under the existing project specs surface.
• Onboarding artifacts are durable project context, distinct from ordinary requirements-grill artifacts and distinct from final spec artifacts.

Q16

Question: What route, metadata, and backlink bookkeeping should onboarding output maintain?

Accepted answer:

• Create or update content/docs/project/onboarding/meta.json.
• Create content/docs/project/onboarding/index.mdx if missing.
• Add onboarding to content/docs/project/meta.json.
• Reconstructed specs must link back to relevant onboarding project-map sections and grill decisions.
• Onboarding artifacts should be discoverable in the routed project wiki and traceable from reconstructed specs.

Branch: Skill Packaging

Q17

Question: Where should docs-onboarding live and how should dp scaffold init distribute it?

Accepted answer:

• Author docs-onboarding first in /Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/docs/docs-onboarding.
• Vendor the skill into Harness under apps/cli/skills/agnostic/docs/docs-onboarding.
• Register the skill in the CLI skill catalog.
• dp scaffold init copies docs-onboarding, requirements-grill, write-backlog, and create-spec.
• docs-onboarding orchestrates existing-project adoption; requirements-phase remains the broader requirements wrapper, docs-ingest-phase remains post-implementation docs ingestion, and create-spec remains the spec structuring skill called after grill closure.

Q18

Question: How should dp scaffold init behave before the next remote baseline includes docs-onboarding?

Accepted answer:

• Stage skill copying should fall back to bundled skill content when the selected baseline is missing a newly-added stage skill.
• This keeps the current executable working with an older remote stable baseline.

Branch: Safety And Cost Controls

Q19

Question: What safety and cost controls should bound Docs onboarding?

Accepted answer:

• Use bounded-depth discovery by default.
• Skip generated, dependency, cache, build, and agent/worktree directories unless a source explicitly points there.
• Deep-read implementation files only to explain a flow, resolve a contradiction, or map a data boundary.
• Persist Project Map and grill status before developer questions so resume does not rescan from zero.
• Treat missing remote backlog access or missing local backlog clues as a question for the developer, not as permission to invent context.
• Mark uncertainty with Evidence Level instead of blocking on every low-risk fact.
• Never invent implementation notes, rationale, or tech-debt history without supporting artifacts.
• Do not mutate backlog providers during onboarding.