docs: extraction prompt design and history (updated, for discussion)

[jimnoneill]

This reopens the extraction-prompt design write-up as a living discussion. The original version (#5) was merged before the discussion played out, and main has since moved on, so this brings docs/prompt-design.md up to date and puts the remaining questions back on the table.

What this doc is

The reasoning behind the LLM extraction prompt has lived in commit messages, changelog entries, and the field-coverage tracker rather than one place. This reconciles three sources: the prompt (EXTRACTION_PROMPT / FALLBACK_PROMPT in extract.py), the poster-json-schema contract (v0.2), and the Poster.json Field Coverage tracker (Poster Sharing sheet).

Updated since #5

• publicationYear is now platform-owned (removed from the model in 0.9.14), not the lone model-owned required field as first written.
• descriptionType is set deterministically to Other (machine summary; Abstract is the author's downstream abstract) and removed from the prompt (see the companion fix fix: tag LLM summary descriptionType as Other (not Abstract); drop from prompt #6).
• Resolved open questions (publicationYear, descriptionType, the vestigial grounding note) are cleared.

Open for discussion

1. fundingReferences: kept as a model field, but the prompt does not currently ask for it (postprocess only enriches funding the model volunteers). Add it to the prompt explicitly?
2. The model-ownership boundary: descriptive/topical content stays with the model; administrative/provenance metadata moves off it. Worth stating as one rule so future field decisions have something to follow.

Docs-only; no code change. The descriptionType value fix and prompt edit are in #6.

Summary by Sourcery

Document the current extraction prompt design and field ownership history, reflecting that publicationYear and descriptionType are now platform-owned and deterministically set rather than model-generated.

Documentation:

• Update prompt-design documentation to describe which metadata fields are model-owned versus platform- or system-owned, including the removal of publicationYear from the model and deterministic handling of descriptionType.
• Clarify the historical timeline of changes to extraction fields, including grounding and later removal of publicationYear and the correction of descriptionType to Other.
• Revise the open-questions section to close resolved issues and focus discussion on fundingReferences coverage and an explicit rule for the model-versus-platform ownership boundary.

[fairdataihub-bot]

Thank you for submitting this pull request! We appreciate your contribution to the project. Before we can merge it, we need to review the changes you've made to ensure they align with our code standards and meet the requirements of the project. We'll get back to you as soon as we can with feedback. Thanks again!

[sourcery-ai]

Reviewer's Guide

Updates the extraction prompt design doc to reflect that publicationYear and descriptionType are now platform-/post-processing-owned rather than model-owned, clarifies how descriptions are typed, refreshes the historical change log, and narrows the open questions to funding references and the model-ownership boundary.

File-Level Changes

Change	Details	Files
Align the field-ownership tables and narrative with current behavior for publicationYear and descriptionType.	Update the summary of which top-level schema fields the prompt asks for so publicationYear is no longer listed as model-produced and is instead described as platform-owned Move publicationYear from the "fields the model is asked for" table into the "fields the model is deliberately not asked for" table, with a note that it is force-nulled and set by the platform Clarify in the descriptions section that only the description text is model-generated and that descriptionType is no longer requested in the prompt but set deterministically to Other in post-processing Adjust the v0.9.3 narrative so descriptionType is described as being set deterministically in post-processing and later corrected from Abstract to Other	docs/prompt-design.md
Refresh the historical timeline and endpoint description to match the current tracker and implementation.	Retitle and expand the publicationYear history entry to describe grounding first and later complete removal from the model and prompts Add a new history item documenting removal of descriptionType from the prompt and its correction to Other, including the earlier flip-flops between Other and Abstract Change the closing sentence about the endpoint of the moves to refer to "all these moves" instead of "all fourteen moves" to include the new entries	docs/prompt-design.md
Replace the original list of open inconsistencies with updated, narrower open questions.	Remove the earlier open questions about publicationYear ownership, descriptionType being asked for but ignored, and the vestigial grounding note Rewrite the open questions section introduction to note that most inconsistencies have been resolved and only two items remain Add an open question proposing that fundingReferences be explicitly added to the prompt JSON shape since it is treated as LLM-sourced elsewhere Add an open question articulating the model-ownership boundary rule (descriptive/topical vs administrative/provenance fields) and suggesting it should be written down as a guiding principle	docs/prompt-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[fairdataihub-bot]

Thanks for making updates to your pull request. Our team will take a look and provide feedback as soon as possible. Please wait for any GitHub Actions to complete before editing your pull request. If you have any additional questions or concerns, feel free to let us know. Thank you for your contributions!

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/prompt-design.md" line_range="233" />
<code_context>
    v0.6.x series). DOIs, ORCIDs, arXiv IDs, ROR, and funder ids are extracted by
    regex and looked up via API rather than trusted from the model.

</code_context>
<issue_to_address>
**nitpick (typo):** Consider capitalizing "ids" to "IDs" for consistency with the other identifiers listed.

To keep acronym capitalization consistent in this list, change "funder ids" to "funder IDs".

```suggestion
v0.6.x series). DOIs, ORCIDs, arXiv IDs, ROR, and funder IDs are extracted by
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

nitpick (typo): Consider capitalizing "ids" to "IDs" for consistency with the other identifiers listed.

To keep acronym capitalization consistent in this list, change "funder ids" to "funder IDs".

Suggested change

	v0.6.x series). DOIs, ORCIDs, arXiv IDs, ROR, and funder ids are extracted by
	v0.6.x series). DOIs, ORCIDs, arXiv IDs, ROR, and funder IDs are extracted by

[fairdataihub-bot]

Thank you for getting this pull request merged. We appreciate your contribution and look forward to your next one!