Finder and Backlog Operating Model Planning Research

Scope and method

This report consolidates two readonly planning lanes plus the earlier provider feasibility audit for the accepted Project Backlog Operating Model specification. It records current implementation facts, planning inferences, conflicts, and runtime proof gates. It does not change the accepted product model or choose new requirements.

The retained immutable specification is eee747e on GitHub. The canonical shared-skills source was inspected on clean main at caa755e3c080f8bc77773bd0ccbea3be935aa5c4. Harness was inspected on team/stefan/finder-phase-write-backlog-improvements; at research time it was four commits behind and three commits ahead of origin/main.

Accepted target topology

The specification fixes this ownership hierarchy and keeps Fog as lateral provenance:

Product / Backlog Root
└── Product Area
    └── Initiative
        └── Epic
            └── Story [exactly one contextual V* milestone]
                └── Task 1..n [required, same V*, blocker relations]

Fog ──records accepted grilling and evidence──> enriched hierarchy and produced work

The three public Finder surfaces are cumulative human-only views over one resumable graph:

business-finder   → Business grilling                          → Area / Initiative / Epic
functional-finder → Business + Functional grilling             → Story@V*
technical-finder  → Business + Functional + Technical grilling → SPEC.md + Task@V* graph

Source: accepted topology, Finder composition, milestone, task, and provenance contracts in the immutable specification, especially AC-001 through AC-018.

Facts: canonical shared-skills source

Finder currently implements the former lifecycle

The current source surface is limited to:

skills/phases/finder-phase/
├── SKILL.md
├── agents/openai.yaml
└── references/
    ├── convergence.md
    ├── frontier-lifecycle.md
    └── root-routing.md

finder-phase/SKILL.md currently exposes chart and work modes and graduates a Fog-derived question into grilling, research, or prototype work. The references encode the former frontier/convergence lifecycle rather than one Fog with Business, Functional, and Technical children. The current wayfinder lifecycle contract and tests/wayfinder-lifecycle.contract.test.mjs reinforce that model.

Primary sources:

/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/references/frontier-lifecycle.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/finder-phase/references/convergence.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/wayfinder/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/tests/wayfinder-lifecycle.contract.test.mjs

There are no canonical business-finder, functional-finder, or technical-finder skill directories. The accepted direct-composition wrappers and the engine phases ensure-fog, business-grilling, functional-grilling, technical-grilling, research, prototype, reconcile, target-return, and handback therefore do not yet exist.

`write-backlog` currently implements the former projection

The current writer is one large entrypoint plus broad reference and provider assets:

skills/agnostic/requirements/write-backlog/
├── SKILL.md
├── REFERENCE.md
├── EXAMPLES.md
└── assets/
    ├── concepts/{backlog-model,story-shape}.md
    └── providers/{linear,github-projects,azure-devops,monday}-create-payload.md

Its accepted writer strengths already exist: few coherent product-facing items, full preflight, native relationships, traceability, and provider readback. Its taxonomy and branches do not match the new model:

SKILL.md and REFERENCE.md make post-spec delivery projection create one Epic and its Stories.
assets/concepts/backlog-model.md defines a capability module and project-overview M1 → M2 → M3 milestones.
assets/providers/linear-create-payload.md maps Fog through Epic to overview milestones and treats Stories as inheriting that membership.
The public entrypoint advertises Linear, GitHub Projects V2, Azure DevOps, and monday.com, while the accepted scope is Linear and GitHub only.
No current branch owns Product/Backlog Root, Product Area, Initiative, mandatory Task graphs, contextual V*, initialization/views, Normalization, or distinct delivery facts.

Primary sources:

/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/REFERENCE.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/assets/concepts/backlog-model.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/assets/providers/linear-create-payload.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/requirements/write-backlog/assets/providers/github-projects-create-payload.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-lifecycle.contract.test.mjs
/Users/stefan/Desktop/repos/wearedevpunks-skills/tests/write-backlog-provider-planning.contract.test.mjs

Downstream consumers preserve contradictory assumptions

create-plan/references/backlog-sync.md defines provider Epic as one-spec projection and plan Tasks as internal-only. That would create two divergent Task graphs after provider Tasks become mandatory.
delivery-phase/phases/backlog.md permits write-backlog only after an agent-ready spec, which cannot represent Business and Functional projection.
docs-onboarding/SKILL.md also prohibits backlog mutation before a spec.
design-phase/phases/backlog.md describes only post-spec backlog projection.
implement-spec/SKILL.md, implement-spec/references/lifecycle.md, and Delivery closeout do not require immediate provider updates for start, blocker, pull request, merge, named-environment deployment, and production evidence as distinct observations.

Primary sources:

/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/create-plan/references/backlog-sync.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/backlog.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/implement.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/delivery-phase/phases/closeout.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/planning/implement-spec/references/lifecycle.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/agnostic/docs/docs-onboarding/SKILL.md
/Users/stefan/Desktop/repos/wearedevpunks-skills/skills/phases/design-phase/phases/backlog.md

Facts: Harness integration surface

Settings migration is a narrow existing CLI path

.devpunks/settings.json currently stores a legacy Linear /project/ URL in backlogProjectUrl. hi ensure already reads current settings, prompts for the four settings values, preserves unrelated settings, and writes only the reconfigured settings result. The gap is URL semantics: settings-selection.ts accepts any absolute HTTP(S) URL and accepts the current legacy default when the operator presses Enter. It does not distinguish a Linear Project URL from the required Product/Backlog Root Initiative URL.

Primary sources:

.devpunks/settings.json
apps/cli/src/cli/ensure-command.ts
apps/cli/src/scaffold/settings-selection.ts
apps/cli/src/features/project-settings/model.ts
apps/cli/src/features/project-settings/service.ts

Canonical sync has an explicit immutable pin

Harness pins shared skills to caa755e3c080f8bc77773bd0ccbea3be935aa5c4 in both the sync script and its test. Canonical edits must be committed and pushed in /Users/stefan/Desktop/repos/wearedevpunks-skills first, then Harness must update the pin, run bun run sync:skills, and verify the projection receipt records that exact new source SHA.

Primary sources:

apps/cli/scripts/sync-skills-repo.mjs
apps/cli/src/scripts/sync-skills-repo.test.ts
root AGENTS.md shared-skill source-of-truth rule

Catalog, prompt, and docs surfaces assume one implicit Finder

The CLI catalog and planning pack contain finder-phase only. Root scaffold prompt text routes foggy work to Finder, conflicting with the accepted rule that all four Finder surfaces are human-only and never auto-invoked. The public wiki documents one Finder lifecycle and the prior brainstorming-to-requirements flow.

Primary sources:

apps/cli/src/data/catalog/skills.ts
apps/cli/src/data/catalog/packs.ts
apps/cli/src/content/prompts.ts
apps/cli/src/content/scaffold-copy.ts
apps/wiki/content/docs/harness/entrypoints/finder-phase.mdx
apps/wiki/content/docs/harness/entrypoints/brainstorming-requirements-backlog.mdx
apps/wiki/content/docs/harness/skills-and-packs/skill-reference.mdx
apps/wiki/content/docs/harness/skills-and-packs/skill-model.mdx
apps/wiki/content/docs/harness/skills-and-packs/skill-packs.mdx
apps/wiki/content/docs/harness/skills-and-packs/phase-wrappers.mdx
docs/README.md
docs/runbooks/hi-cli-scaffolding.md

Release scope is mixed and major

The current CLI version is 3.3.4. The user-required major bump makes the target 4.0.0. Both CHANGELOG.md and BASELINE_CHANGELOG.md are required delivery outputs, so release classification is mixed under repository policy. The baseline compatibility range must move to the accepted major line (planning lane target >=4.0.0 <5) rather than retaining the current >=3.3.4 <3.4.0 range.

Primary sources:

apps/cli/package.json
CHANGELOG.md
BASELINE_CHANGELOG.md
root AGENTS.md release-classification and compatibility rules

Provider feasibility facts

Linear

Linear Initiatives can nest as sub-initiatives up to five levels and may have multiple parents. Projects do not nest. Issues belong to at most one Project, can have parent/sub-issue hierarchy, and can carry one Project milestone. Project milestones are local to one Project; Cycles are a separate sprint construct. Linear supports explicit related, blocking, blocked, and duplicate issue relations.

Primary sources:

These capabilities support the accepted semantic mapping:

top Initiative → nested Product Area Initiative → nested Initiative
               → Epic Project → Story Issue → Task sub-issue

Because Linear permits multiple Initiative parents, the accepted exactly-one Product Area rule must be validated by write-backlog; the provider does not enforce it. Because a milestone is Project-local, a Story or Task can carry the required V* only when it belongs to the Epic Project that owns that milestone.

GitHub

GitHub Projects V2 is a flat operating surface containing items, fields, and views; it has no native nested Initiative or nested Project object. Issues may belong to multiple Projects V2. Repository issues carry at most one repository milestone. Sub-issues can nest to eight levels with up to 100 direct children. GitHub supports issue dependencies, but does not expose a Linear-style generic related relation.

Primary sources:

Authenticated live GraphQL introspection on 2026-08-26 confirmed:

CreateIssueInput has projectV2Ids, milestoneId, and parentIssueId.
Mutation fields include createProjectV2, createProjectV2Field, createProjectV2View, updateProjectV2View, addSubIssue, and addBlockedBy.
Issue exposes parent, subIssues, blockedBy, and blocking.

Evidence command:

gh api graphql -f query='<schema introspection for CreateIssueInput, Mutation, Issue>'

The accepted GitHub mapping is therefore semantic rather than structurally identical to Linear:

one Project V2 operating surface
├── configured Product Area / Initiative fields or upper issue levels
└── Epic Issue → Story sub-issue → Task nested sub-issue

Fog provenance can use a Linear related relation plus body link. GitHub needs a durable body/reference backlink and, when configured, a provenance field; parent or blocker edges may be used only when those semantics are true.

Across both providers, no native semantic duplicate detector establishes the accepted identity. Safe enrichment must resolve a configured provider ID or durable identity marker, read current state, enrich exactly one match, create only on no match, and stop on multiple candidates. Title-only matching cannot authorize writes. Source: provider documentation above and AC-020, AC-021, AC-024, AC-026.

Planning inferences from accepted requirements

These are implementation boundaries derived from the specification and current source, not new product decisions.

Shared-skills boundary

Add the three thin human-only wrappers and refactor finder-phase into the single graph engine. A wrapper must directly compose the engine contract with a fixed target depth; wording that asks the model to invoke another human-only skill is mechanically contradictory.
Refactor write-backlog into a concise branch router with disclosed references for project context, initialization, Fog intake, Business, Functional, and Technical projection, reconciliation, Normalization, delivery status, and Linear/GitHub provider behavior.
Preserve the current strong ticket-writing and mutation transaction behavior while replacing the old taxonomy and provider scope.
Reconcile wayfinder, create-plan, implement-spec, docs onboarding, design, and Delivery so one provider Task graph and one mutation authority remain.
Keep all provider mechanics in write-backlog; Finder and Delivery select a branch and supply accepted or observed evidence.

The skill documents and any agent prompts fall under writing-for-agents: primary steps stay in the entrypoint, provider/stage branches disclose only when selected, and each gate has a checkable completion criterion.

Harness boundary

Land and push canonical shared-skills changes before changing Harness's pin.
Synchronize projections and update the exact source receipt.
Add catalog/pack entries for the three wrappers and preserve the engine as a human-only explicit surface.
Replace root auto-routing language with human-invocation guidance.
Extend hi ensure validation and guidance for the Linear Initiative URL while preserving all other provider behavior and unrelated settings.
Update wiki and runbook documentation with the accepted topology, cumulative Finder flow, Product Map/Roadmap/Fogs/Current Delivery views, and Normalization preview/approval boundary.
Complete the requested 4.0.0 package and mixed CLI/baseline changelog changes after reconciling the topic branch with current origin/main.

Dependency boundaries

The source-authority order is hard:

canonical shared-skills commit + push
  → Harness sync pin + projected skills
  → catalogs, prompts, CLI settings migration, docs
  → cross-surface validation
  → mixed release evidence

Within canonical skills, independent first seams are Finder graph/wrappers, writer references/provider contracts, and downstream Delivery/task-state consumers. Integration must then prove one lifecycle and one Task graph. This is an ownership observation for planning; the execution plan remains responsible for assigning non-overlapping workers and exact waves.

Required test and validation seams

Shared-skills contracts

Contract coverage must demonstrate:

all four Finder surfaces are human-only in skill and OpenAI metadata;
three thin wrappers share one engine and target depth;
new/resumed Fog routing, child Stage/cardinality, accepted lower-stage reuse, cold resume, support-work cycles, stale/contradictory evidence, human_steering_required, and target-depth return;
stable-identity-only writes, exact-one V*, milestone movement approval, required atomic Task graph, missing target/self-edge/cycle/future-iteration rejection;
Linear and GitHub mappings, full preview, exact relationship/readback, and unsupported provider fail-closed behavior;
start, blocker, pull request, merge, staging, and production as distinct facts, with production-only Fog completion;
$wait-what language and $show-me visuals at the accepted Business and Functional decision gates.

Current test sources to replace or extend:

tests/wayfinder-lifecycle.contract.test.mjs
tests/write-backlog-lifecycle.contract.test.mjs
tests/write-backlog-provider-planning.contract.test.mjs
tests/fixtures/write-backlog-provider-planning.json
tests/requirements-grill-composition.contract.test.mjs
tests/show-me.contract.test.mjs

Harness contracts

Harness needs focused tests for selectRepoSettings and runEnsure, settings readback, sync pin/receipt, catalog/pack content, prompt invocation policy, and the projected shared-skill contracts. The delivery-wide validation set identified by the lane is:

canonical shared-skills Node contract tests;
CLI focused settings, sync, catalog, prompt, build, and check tests;
bun run --cwd apps/wiki check:content;
root check and test suites;
baseline build and release classifier evidence.

Exact commands and worker ownership belong in the execution plan.

Conflicts to resolve during implementation

Former Finder lifecycle versus cumulative wrappers. Current chart/work/graduation semantics and wayfinder tests compete with the accepted child-stage graph.
Human-only composition versus invocation wording. A user-invoked wrapper cannot rely on model invocation of another user-only skill. The wrapper must apply the engine contract directly.
Global post-spec gate versus staged projection. Current Delivery and docs guidance blocks Business and Functional writes before a spec, while the accepted writer has pre-spec stage-authorized branches.
Internal plan Tasks versus provider Tasks. Current create-plan wording would preserve a second Task graph after Tasks become required provider work.
M* overview milestones versus contextual V*. Current writer assets assign milestones across Fog-through-Epic; accepted milestones belong exactly to every Story and Task and may be reused.
Four advertised providers versus two accepted providers. Azure DevOps and monday.com remain implementation assets but cannot stay reachable as supported public branches for this capability.
Root Finder auto-routing versus human-only surfaces. Current scaffold prompt guidance must stop implying automatic Finder activation.
Legacy settings URL versus new authority. Pressing Enter in hi ensure currently preserves the invalid legacy Linear Project destination.
Structural preview versus approval. A $show-me preview is evidence for human approval; it is not approval itself.

Unresolved and runtime proof gates

These gates must remain explicit; none authorizes a new product decision.

GitHub nested Task readback: schema introspection proves capability names, not that the configured repository, Project V2, permissions, fields, views, nested Task, blockers, milestone, and provenance all round-trip. The first workflow-created Story-to-Task graph needs exact live readback before runtime support is claimed.
Linear workspace representation: official capabilities support the mapping, but current workspace Initiative nesting, Epic Project ownership, milestone, labels/Stage representation, and permissions need preflight and exact readback.
Cross-repository GitHub milestones: repository milestones do not provide a shared namespace across multiple repositories in one Project V2. A concrete multi-repository target must fail closed or return for human steering unless the accepted contextual V* is representable.
Provider identity: title similarity cannot settle existing Product Area, Initiative, Epic, Story, Task, or Fog provenance. Ambiguous current state is a zero-write result.
Branch reconciliation: the topic branch was behind origin/main; delivery must reconcile before release evidence and report any scope conflict rather than silently choosing one side.
Baseline publication: repository changes can prove build/classification and candidate readiness, but hosted publication still requires protected authority and provider readback.
CI/CD automation: pipeline event design, branch protection, release-branch provenance, and automatic status adapters remain explicitly parked. Delivery records only directly observed evidence in this scope.

Planning conclusion

The accepted capability is implementable without a new product decision, but it is a coordinated source-first migration rather than a local skill edit. The critical path is canonical Finder/writer/downstream contract reconciliation, followed by an exact Harness projection, operator migration behavior, docs, and mixed major-release evidence. Runtime provider support remains fail-closed until the configured Linear and GitHub topologies are written and read back exactly.

Finder and Backlog Operating Model Planning Research

On this page