research-logging

Files (200)

• SKILL.md
• openai.yaml · agents/
• file-adhoc.md · references/
• file-data-index.md · references/
• file-entry-commands.md · references/
• file-entry-labels.md · references/
• file-entry-naming.md · references/
• file-entry.md · references/
• file-presented-evidence.md · references/
• file-references.md · references/
• file-reproduction-records.md · references/
• file-retention.md · references/
• file-script.md · references/
• file-summary-ai-use.md · references/
• file-summary-reproduction.md · references/
• file-summary-validation.md · references/
• file-summary.md · references/
• file-validation-records.md · references/
• operation-record-content.md · references/
• operation-record-existing.md · references/
• operation-record-new.md · references/
• operation-record-start.md · references/
• operation-record.md · references/
• operation-reference.md · references/
• operation-reorganize-documents.md · references/
• operation-reorganize-identity.md · references/
• operation-reorganize-transfer.md · references/
• operation-reorganize.md · references/
• operation-repair.md · references/
• operation-replace.md · references/
• operation-reproduce.md · references/
• operation-review.md · references/
• operation-update-summary.md · references/
• operation-validate.md · references/
• provenance-patterns.md · references/
• commit-input.md · references/provenance-patterns/
• configuration-origin.md · references/provenance-patterns/
• cross-entry-reuse.md · references/provenance-patterns/
• directory-artifacts.md · references/provenance-patterns/
• external-simulation-origin.md · references/provenance-patterns/
• named-artifacts.md · references/provenance-patterns/
• retained-support.md · references/provenance-patterns/
• selected-directory-identity.md · references/provenance-patterns/
• record-evidence-definition-direct-tables.md · references/
• record-evidence-definition-numeric.md · references/
• record-evidence-definition-outputs.md · references/
• record-evidence-definition-sources.md · references/
• research-log-writing.md · references/
• catalog.md · references/review-lenses/
• citation-support.md · references/review-lenses/
• claim-calibration.md · references/review-lenses/
• claim-support.md · references/review-lenses/
• cross-entry-consistency.md · references/review-lenses/
• decision-support.md · references/review-lenses/
• evidence-coverage.md · references/review-lenses/
• evidence-selection.md · references/review-lenses/
• implementation-fidelity.md · references/review-lenses/
• methodological-validity.md · references/review-lenses/
• numerical-validity.md · references/review-lenses/
• presentation-consistency.md · references/review-lenses/
• …and 140 more

SKILL.md (first lines)

# Research Logging

Use this skill for Record, Replace, Update Summary, Repair, Reorganize, Review,
Validate, and Reproduce.
Record performs and documents an investigation as one workflow and also starts
logs. Its production checks do not establish validation. It normally authors
Markdown and uses command sync before execution and evidence compare/sync after it;
Record's focused references teach the definition and ownership details.

Research outside the log is adjacent work, not another operation. A log's
presence does not authorize Record. Leave it unchanged for exploratory work
without preservation intent; route later requests to retain, add, present,
cite, or use that work through Record.

## Choose The Operation

Choose the core operation:

- Starting a new log; investigating, implementing, running, analyzing, or
  recording research; continuing work; or working with support material,
  scripts, generated results, data organization, or command output: read
  `references/operation-record.md`.
- Explicitly replacing or removing a named experimental section and its owned
  material: read `references/operation-replace.md`.
- Researcher-requested or approved updates to current understanding or
  follow-ups in the log summary: read `references/operation-update-summary.md`.
- Researcher-directed semantic review of a research log's analysis, evidence,
  record, or a named review lens or group: read
  `references/operation-review.md`. Semantic Review is costly; never initiate
  it as part of another operation or as an ordinary completion check.
- Independent mechanical validation, or researcher-requested read-only
  investigation of named mechanical-validation findings: read
  `references/operation-validate.md`. The validation run is code-only; neither
  path becomes semantic review or reproduction. Those remain separate
  workflows.
- Explicit mechanical reproduction of a maintained log or one entry: read
  `references/operation-reproduce.md`. Ordinary reproduction does not target
  one command. Reproduce is CLI-owned: `evidence.json`, `data.json`, and
  `pyrun.json` collectively provide authored pre-acceptance graph/execution
  authority; after acceptance, the immutable plan in run-local `state.sqlite`
  owns durable execution, resume, and job state. `results.sqlite` owns only
  disposable query results. Code currentness comes from the nullable
  project-local effective-code fingerprint, not raw script bytes. Execution
  and analysis share the runner-owned import context defined by
  `references/file-script.md`. A supported changed source is runnable;
  an unavailable effective-code fingerprint is also runnable and is selected
  again because currentness cannot be established;
  `references/operation-reproduce.md` owns matched-source reconciliation,
  differing-result reuse, and explicit promotion. Reproduce
  never becomes Record, Review, or Validate.
- Explicit correction of a research-log finding, repair batch, finding type,
  malformed or legacy state, transaction residue, or other identified log
  defect: read `references/operation-repair.md`. Correction language such as
  repair, fix, resolve, correct, clean up, or remove authorizes Repair when the
  requested target and corrected state are clear. A failed authoring command
  or reported finding alone does not. Route an explicit check of one repaired
  invocation here; ordinary one-command reproduction is unavailable.
- Researcher-requested reorganization, or a specific Reorganize recommendation
  that the researcher has approved: read
  `references/operation-reorganize.md`. Review may recommend Reorganize but
  cannot authorize it.

For standalone reference lookup, viewing, or candidate management, read
`references/operation-reference.md`. During Record, route citation and BibTeX
changes through `references/operation-record.md`.

## Authority Across Operations

Resolve the operation and authorized scope from the current researcher request
and durable workspace state. Do not let older conversation content expand
either. Ask before editing when ambiguity risks changing research meaning.

If the user's wording is ambiguous between recording and updating the summary,
prefer recording unless the user clearly asks to change the summary. If both
are requested, complete Record before Update Summary. If it is ambiguous
between review and editing, report findings first and ask before applying fixes
unless the requested correction is explicit; route an explicit correction of
an identified defect through Repair.

Treat `Validate`, `Review`, and `Reproduction` as strong indicators of the
corresponding operation, but interpret the complete request and ask when the
intended operation remains unclear. The researcher does not need to describe
Validate as “mechanical.” Treat a bare request to check or verify a research
log as ambiguous and ask whether the researcher wants Validate, Review, or
Reproduction. Start Review only when the researcher directly requests the act
of reviewing a target or asks to apply a named or naturally described review
lens or group. Review-direction language such as review, audit, assess,
evaluate, critique, or check for a semantic concern can establish that request.
A bounded question that merely overlaps a lens does not start Review.

A request to inspect, explain, triage, or determine the cause of named
mechanical-validation findings routes to Validate's read-only diagnosis path,
not Review or Repair. It does not authorize a validation rerun or correction.
If the same request also asks to correct the diagnosed condition, route it
directly to Repair and use the narrowest named finding, repair batch, or
finding type as its scope. A hypothetical question about how one might fix a
condition remains diagnosis. When several corrected states are plausible, ask
which state the researcher intends before editing.

Do not infer Replace from a revision, rerun, correction, or reorganization
request. Use it only when the researcher explicitly intends superseded
experimental work to leave the active log.

Reorganize is separately authorized structural work. Review may recommend it
but cannot authorize it. A failed command, validation finding, or malformed
state does not start Repair without an explicit correction request.

## Universal Boundaries

- Do not decide what conclusion, interpretation, method choice, validation
  outcome, or next research direction the log should treat as accepted unless
  the user states that decision.
- Do not write or revise `Decisions:` content unless the researcher explicitly
  directs you to record or revise the specific decision.
- Preserve existing researcher wording unless the user asks for rewriting.
- Do not invent evidence, validation, references, results, uncertainty,
  decisions, or conclusions.
- Do not use generative AI to create data, results, figures, or citations.
- Treat maintained summaries, entries, evidence records, scripts, artifacts,

From nvnunes/astro-agents, MIT.

More from nvnunes/astro-agents