Skip to content

Docs: import-format guide references RANK_SPEC.md, which is unreachable via guide show/list #34

Description

@johnjosephhorton

Summary

The import-format guide references RANK_SPEC.md for the full rank-battery import/validation flow, but that document is not reachable through the documented mechanism (zwill guide show) and does not appear in zwill guide list.

Repro

zwill guide show import-format includes:

A rank battery is a set of per-item questions scored together … See RANK_SPEC.md for the full rank flow.

But:

zwill guide list
#  -> only: agent-workflow, interpreting-results, import-format

zwill guide show RANK_SPEC
# {
#   "status": "error",
#   "errors": [{ "code": "not_found",
#     "message": "Unknown zwill guide: RANK_SPEC.",
#     "context": { "known_guides": ["agent-workflow","import-format","interpreting-results"] } }]
# }

Impact

The canonical rank-battery import shape (how _RANK / _GROUP columns map to rank_task_id, expected answer encoding, direction) is effectively undocumented. I had to infer it and rely on the auto-detector. (The auto-detector did work well — it grouped the 4 batteries and inferred 1_is_best — but the reference doc it points you to is a dead link.)

Suggested fixes

  • Ship RANK_SPEC as a guide show-able guide (add it to the bundled guides), or
  • Replace the reference in import-format with the actual content / a reachable link.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions