second-coder-codex

---
name: second-coder-codex
description: Guide researcher-approved meta-analysis second coding entirely in Codex, with PDF preparation, paper-by-paper estimate approval, independent per-paper coding, and evidence-based grouped human–AI adjudication through an interactive panel in the Codex conversation. Use for research coding projects with a user-supplied codebook and template.
---

# Second coder in Codex

Use English for guidance, files, and default outputs. Keep reusable instructions separate from project-specific rules. Do not import LCAPM or other pilot conventions into unrelated research.

## First use and researcher orientation

Before requesting materials on first use, read [researcher guidance](references/researcher-guidance.md). When the researcher says they want to start, proactively explain the purpose, every stage (1, 2A, 2B, 2C, 3), what Codex does, what the researcher supplies and decides, and the final folder deliverables. Include the qualitative time reminder: rule discussion/review, estimate selection and AI-human adjudication can require substantial researcher time. Then request only current-stage materials. If giving an installation-completion introduction, use the same guidance after verifying installation; do not claim that file copying alone automatically triggers the skill. Avoid repeating an orientation already given in the same onboarding exchange. On resumption read the saved state and introduce the current step, not the entire workflow again.

Before an extended Stage 1 discussion, follow [startup and resumption](references/startup-and-resume.md): establish the project folder, proactively prompt the researcher to choose or confirm a model and reasoning setting, record the confirmed settings, check access/runtime readiness, and display the data-free compatibility check. Offer a recommendation based on current official OpenAI guidance and the researcher's accuracy, cost and processing-time preferences. Confirm the researcher's selection before continuing the Stage 1 discussion; do not claim that a recommendation or consent has changed the active settings. On resumption reuse the recorded choice unless the settings have changed or were never recorded. A successful marked return message verifies the panel-to-chat path; creating the file alone does not. Reuse a saved check in the same client/session unless a capability changes or fails.

Independent AI coding means withholding completed human coding until the AI output is frozen. The researcher first approves the eligible estimates, so record selection is researcher-reviewed rather than an unaided AI selection test. Explain this in the opening overview.

This is a second-coding workflow for studies already selected by the researcher. Use the designated source versions corresponding to independent human coding. Do not automatically search for a newer paper version, replace sources or repeat study screening. If sources conflict, ask which designated material applies without reading GT early. Retrieval of a missing supplement is distinct from replacing the study and follows the approved source-search permissions.

## Guide and resume

Codex owns progression. After each completed step or researcher decision, state what was completed, explain the next step, and perform the next authorized action. Do not wait for “continue.” Pause for required materials, initial model/settings confirmation, explicit eligibility approval, substantive rule decisions, or final adjudication choices. At the Stage 3 panel handoff, await the researcher-confirmed submission through the conversation interface as specified below. Silence and a request to edit a list are not approval. Technical preparation, validation, and merging need no extra workflow approval.

Maintain `PROJECT_GUIDE.md` as the project entry point, linking the existing progress, approval and decision records as described in startup and resumption; do not replace their saved-state formats or duplicate approvals. Persist the current stage, batch, prompt/template versions and hashes, per-paper status, approval records, and next pending decision in the project folder. On resumption read these records first. A new session must not infer approvals from an output filename or redo settled decisions. Each approval identifies the exact saved version and date. Keep original inputs and superseded outputs.

Start by requesting the research question and eligibility criteria, codebook/variable definitions, blank coding template, and representative papers with relevant supplements. Ask for the folder and designated files. Explain that incomplete materials can be clarified through discussion. Ask the researcher to withhold completed human codesheets, GT, and adjudicated datasets until Stage 3. If these are already present, exclude them from reading and worker inputs until then.

Explain each requested file's purpose and suitable format using the current-stage checklist in researcher guidance. Accept a local folder path with designated files or available attachment/drag-and-drop options; confirm actual accessible files and name missing items. Do not repeatedly request material already supplied, require the full corpus, or turn technical file handling into additional researcher approvals. When waiting, state the exact missing material or decision and what it enables. Keep chat guidance focused on the current action; the README provides the complete manual.

## Stage 1 — unchanged professor workflow

Read and follow [the original Stage 1 skill](references/stage1-original.md) and [its README](references/stage1-original-readme.md). The original Stage 1 skill is preserved byte-for-byte; its README uses this package's installation name and paths. The chosen extraction tool is Codex. Preserve its substantive sequence, including fresh independent prompt audit, optional external review, and explicit final approval. Do not silently skip independent review or label self-review independent.

These preserved files are references within the single installed `second-coder-codex` skill; do not direct the researcher to install additional component skills. Use the package README for installation and this workflow's transitions. Strengthen user-facing guidance around the existing Stage 1 decisions without repeating its reviews or approvals. Explain that the questioning makes eligibility criteria and variable definitions explicit in the approved prompt. Give the Stage 1 planning allowance in researcher guidance, with its qualification; do not present it as measured study workload.

For this integrated workflow the AI export has the template columns followed by one authorized audit column, `AI_reason`. Explain this convention during Stage 1 and include it in the approved output contract; keep the user's blank data template unchanged. If that name already exists, resolve the collision with the researcher. This packaging convention does not change the preserved Stage 1 source. No other extra codesheet columns are authorized by this skill.

## Stage 2 — batch preparation, approval, coding

Read [Stage 2 procedures](references/stage2.md). After Stage 1 approval ask for the current batch, approximately five papers plus corresponding supplements; the entire corpus is unnecessary. Reuse existing approved rules for later batches. Confirm only missing or ambiguous file designations. Stage 2A is a fixed part of the workflow. Do not ask whether to use it. Immediately after Stage 1 approval, announce that 2A is next and that 2B (eligible-estimate selection) follows preparation. If batch sources are already designated, start 2A in the same turn; otherwise request only the missing sources. A saved preference to skip 2A does not override this requirement. Follow the transition messages and failure handling in Stage 2 procedures.

- **2A:** Prepare page-marked text and relevant images, check readability, and keep complete original PDFs accessible. After preparation, announce and begin 2B without waiting for “continue.”
- **2B:** Review eligibility paper by paper, checking references to appendices/supplements against the provided material before each paper's list is approved. Report missing or mismatched sources and their possible impact; do not describe incomplete-source screening as complete. Save explicit approvals, mechanically merge all approved lists, and obtain final master-list confirmation.
- **2C:** Start fresh independent per-paper coding agents after master confirmation. Schedule according to actual available slots rather than assuming five simultaneous workers. Supply only approved rules, the blank template, that paper's approved list, full PDFs/supplements and Stage 2A reading aids. Do not supply human codesheets, GT, prior adjudicated values, or other workers' outputs. Use a minimal task-specific context rather than inheriting unrelated conversation.
- Validate one-to-one approved estimate coverage, schema, allowed values and verifiable calculations; merge per-paper files into `AI_Codesheet.csv`. Preserve per-paper outputs. `AI_reason` contains English source locators, important decisions, calculation inputs/methods, and uncertainties. Do not duplicate routine reasons in a separate evidence ledger.

If subagents are unavailable, disclose the limitation and offer an isolated-session or sequential fallback; do not claim independence or parallel execution that did not occur. Do not wait indefinitely for capacity. Coding uncertainty follows approved missing-value rules and is logged. Rediscovered eligibility or rule defects require researcher decisions before affected results can be finalized; unaffected work may proceed.

## Stage 3 — grouped, evidence-based adjudication

When Stage 3 review material is ready, or the researcher asks to resume it, build or reuse the in-conversation review panel using [grouped review](references/grouped-review.md#mandatory-in-conversation-handoff). Display the actual panel in the same Codex conversation with all current-paper issue groups, clickable choices and source evidence. Use the host's inline visualization and follow-up capability; do not open a separate HTML file, launch a local service or request a downloaded decision file. In the same reply, say: **Review the evidence and choose your values below. Select Review decisions, then Confirm and send to Codex. I will receive your choices here, verify them and generate the adjudicated codesheet.** For coverage, use Confirm coverage and send to Codex and explain that field review follows. End the turn and await the real confirmation message; background polling is unnecessary. On receipt, save and import the exact marked confirmation through `scripts/review_inline.py`, verify its receipt and continue the existing finalization work without another generic approval. Widget draft state, a screenshot, a source-image request or a generic completion message is not approval. If the host lacks the required inline display or follow-up capability, preserve the review and explain the actual limitation; do not claim successful delivery or silently switch interfaces.

Read [Stage 3 procedures](references/stage3.md), using [the professor's adjudication skill](references/stage3-original.md) as the underlying workflow. Request human coding only after independent AI output is frozen, and only for the paper currently being adjudicated. If the researcher needs help making a current-paper-only export, give software-specific filtering/copying instructions without opening a whole-project human codesheet or revealing later papers; preserve all human-coded estimates for the named paper. Name that paper and ask for its complete human-coded rows in a separate CSV/XLSX, not a whole-project or multi-paper GT file. This per-paper input rule takes precedence over broader material requests in the preserved reference. Match coverage before comparing fields and guide decisions paper by paper. Replace serial chat questions with a grouped panel in this conversation showing all current-paper discrepancies and their source evidence. The researcher inspects evidence, clicks Human / AI / Other value / Defer, and confirms the choices; Codex saves the records, applies the confirmed values, performs the original checks and generates the adjudicated codesheet. Neither human nor AI values automatically take precedence. Follow the evidence-display requirements in Stage 3 procedures, including precise locators and short source excerpts when screenshots cannot be produced or displayed. Use the bundled [in-conversation review helper](references/grouped-review.md) to display the panel and import confirmed host messages into the unchanged codesheet finalizer. This changes the adjudication interface, not comparison rules, eligibility rules, decision authority or final deliverables.

## After each batch

Actively review whether observed problems reveal coding-rule defects. Correct transcription/calculation mistakes without unnecessary prompt changes. Bring substantive prompt revisions to the researcher; explicit approval creates a new version. Identify and revisit affected earlier scope/coding records. Use the latest approved version for the next batch. Keep one consistent approved version per batch; a necessary mid-batch amendment requires checking already completed affected work. Do not silently overwrite old results or initiate a mandatory full-corpus second extraction.

Give the concise prompt-and-batch handoff in [researcher guidance](references/researcher-guidance.md#guidance-at-transitions) before moving on; do not leave the researcher to request the next step.

After final adjudication, organize all generated deliverables by type and create one structured output folder following [output organization](references/output-packaging.md). Make the final agreed codesheet easy to find in `01_Final_Data`, with auxiliary outputs in their designated folders. Explain that this adjudicated codesheet incorporates the researcher’s final decisions and is the data input for their analysis; it is not itself the statistical analysis. Do not compress the output folder into a ZIP. Never deliver a flat dump of files. A batch with unresolved decisions is not a final adjudicated dataset. After batch finalization, delivery and the existing prompt review, proactively return to Stage 2A using [batch selection and continuation](references/stage2.md#batch-selection-and-continuation). Reuse an approved batch plan without reconfirmation; otherwise request the next selection from available remaining papers, or request missing sources. Reuse the approved prompt rather than restarting Stage 1. When no papers remain, report completion and stop the batch loop; respect an explicit request to pause or stop.

• SKILL.md 14 KB
• assets/compatibility-check.html 2 KB
• assets/grouped-review.html 21 KB
• references/grouped-review.md 20 KB
• references/output-packaging.md 6 KB
• references/researcher-guidance.md 11 KB
• references/stage1-original-readme.md 4 KB
• references/stage1-original.md 7 KB
• references/stage2.md 16 KB
• references/stage3-original.md 7 KB
• references/stage3.md 13 KB
• references/startup-and-resume.md 11 KB
• scripts/check_client.py 6 KB
• scripts/check_codesheet.py 3 KB
• scripts/merge_codesheets.py 3 KB
• scripts/package_outputs.py 9 KB
• scripts/prepare_pdfs.py 6 KB
• scripts/render_evidence.py 3 KB
• scripts/review_bridge.py 14 KB
• scripts/review_inline.py 16 KB