Getting started with texanshootR

texanshootR is a terminal-first specification-search engine. The main entry point is shoot(). It opens a wall-clock budget, fires at the specification space, and returns a tx_run carrying the highlighted result and the audit trail.

A first run

library(texanshootR)

run <- shoot(mtcars)
print(run)
summary(run)

shoot() flails opportunistically across predictor subsets, transformations, interactions, outlier exclusions, subgroup splits, and — as the career advances — alternative model families. The print method leads with the shooter’s face and the emotional arc the run followed (composed -> resolved, panicked -> resolved (last-minute), escalated to derived metrics) before the formula and the p-value.

Every run is deterministic given a seed. The seed, R version, package version, and a hash of the search trace are recorded on the returned object so the full search can be replayed.

The publication chain

A finished tx_run that clears p <= 0.05 is shippable. The first shippable run opens a publication chain — six output stages, redeemed in order:

abstract(run)            # one-paragraph deadpan summary
manuscript(run)          # IMRaD draft; Methods match the winning spec
presentation(run)        # 8-slide deck; residual plot on slide 7
reviewer_response(run)   # opens "we thank the reviewer..."
graphical_abstract(run)  # the figure your PI will retweet
funding(run)             # the next grant, citing the just-shipped finding

Finish the chain through your currently-unlocked prefix and you collect a length-bonus on top of the per-stage XP.

The chain breaks — bonus forfeit, partial XP kept — if you fire a fresh shoot() before finishing. Calling the wrong stage (or the wrong run) signals a tx_chain_error but leaves the chain open so you can retry the correct stage.

Aliases are accepted: powerpoint (= presentation), reviewer (= reviewer_response), graphical (= graphical_abstract).

XP, chain length, career tier

The chain prefix you can redeem grows with cumulative XP. Career tier is a label derived from that prefix:

Chain length	New stage	XP needed	Career tier
1	`abstract()`	0	Junior Researcher
2	`manuscript()`	5	Postdoc
3	`presentation()`	15	Postdoc
4	`reviewer_response()`	30	Senior Scientist
5	`graphical_abstract()`	55	Senior Scientist
6	`funding()`	90	PI

The tier label is cosmetic. The chain length is the real gate.

Auto-generating the chain

Output flags on shoot() auto-generate the chain prefix needed to reach the highest enabled flag, in order. So a shippable run with presentation = TRUE produces abstract, manuscript, and presentation in one go — provided each one is unlocked:

run <- shoot(mtcars, presentation = TRUE)

Files land in tempdir() by default. Override with output_dir = or options(texanshootR.output_dir = ...). Each generator returns the file path invisibly.

Locked stages and broken chains

Locked calls, the wrong run, and out-of-order calls all signal a structured tx_chain_error. A locked stage in a fresh profile looks like this:

manuscript() requires:
5 XP (chain length 2)

Current XP:
0

Scripts can branch on the reason field:

res <- tryCatch(manuscript(run), tx_chain_error = function(e) e)
if (inherits(res, "tx_chain_error")) {
  res$reason   # one of: not_unlocked, no_active_chain,
               #         wrong_run, wrong_stage
}

Inspect the live HUD with progress():

progress()

It prints chain length, current XP, next unlock, what’s still locked, and the active chain window if one is open.

Career, achievements, cosmetics

career()        # tier, runs, favourite method, opaque scores
achievements()  # 20 unlockable badges; hidden ones show as ???
wardrobe()      # equipped cosmetic slots (hat, badge, cloak, poncho, lanyard)
run_log()       # tibble of every run on this profile

Hidden achievements appear as ??? until unlocked. New cosmetics auto-equip when their unlocking achievement fires; override the selection with wardrobe(slot, id).

Persistent state

The researcher profile persists under tools::R_user_dir("texanshootR", "data") as flat YAML. The first interactive save prompts before writing anything to disk. Decline the prompt, or opt out entirely with:

options(texanshootR.save_enabled = FALSE)

and the package becomes stateless: every call is independent, progression sits inert at Junior Researcher, and the chain never opens beyond abstract().

To pre-consent (CI, scripts, the impatient):

options(texanshootR.consent = TRUE)