topic-feasibility-screener: a Codex skill that scores empirical research topics before you commit

The problem: a rough idea, a dataset, and no way to rank the options

The gap this project targets is narrow and real. A researcher has a dataset and a vague direction, and needs to know which of several possible topics is worth the next six months. The README frames the skill around two separate questions: theory feasibility, meaning a clear research question, adjacent literature, a plausible mechanism and a credible gap; and data feasibility, meaning usable variables, variation, sample size, interpretable roles and a minimal empirical signal. Both must hold. A topic that fails either one is a bad bet regardless of how interesting it sounds.

The intended audience is stated plainly: early-stage thesis and paper development in accounting, finance, economics, management, corporate governance, digital transformation, ESG, audit, disclosure and capital-market research. That is a specific list. It is not a general-purpose research assistant, and nothing in the README suggests it handles qualitative designs, experiments or survey instruments.

The design decision worth noting is what the skill refuses to do. The README states that it does not treat a significant coefficient as a publishable result. Screening significance is a filter, not a finding, and the guardrails repeat that a high dashboard rank is not evidence of publishability. That stance is more conservative than most tooling in this space, and it is the main reason the output is worth reading at all.

How the screening pipeline actually works

The entry point is scripts/research_topic_lab.py. It reads a .csv or Stata .dta file, profiles the variables, and writes variable_profile.csv. From the usable variables, plus nearby datasets in the same directory when scanning is enabled, it generates candidate topics and keeps them connected to the user's rough idea through a topic alignment score.

Literature search runs as query families rather than a single query string. The diagnostics file literature_query_diagnostics.csv records the query family, provider status, raw hits, valid hits, relevant hits and error messages, so a silent provider failure is visible instead of being absorbed into a low theory score. Papers are then classified into four evidence classes. direct means both sides of the candidate relationship appear in the paper text. bridge means adjacent concepts support the theoretical link, with the README listing information assets, intellectual capital, intangible resources, data valuation, data disclosure, investor judgment and information environment as examples. background is one-sided or contextual evidence, and weak is low relevance or insufficient anchors.

The scoring layer is where the project makes its most interesting argument. When direct_evidence_hits is zero, a keyword-only tool would call the topic unfounded. Here, dense and conceptually close bridge literature raises the innovation gap score instead, because the README treats a frontier gap supported by adjacent literature as different from a genuine theory vacuum. An evidence_profile field states which of the two situations applies. Whether that distinction survives contact with a reviewer is an open question, but it is a defensible position and it is stated openly rather than buried in a heuristic.

After ranking, the top three topics get a second pass: fixed-effect checks and placebo or permutation-style diagnostics where the data structure allows. The README does not specify what happens when the structure does not allow it, which is a gap worth knowing about before you rely on second_pass_validation.csv.

Installing it and running a first screening

The repository is a Codex skill, so the install path is the skill directory rather than a package index. The top-level entries are LICENSE, README.md, SKILL.md, agents/, references/ and scripts/. Place the repository where your Codex setup loads skills, then invoke the script directly. The README's first example is a single positional argument for the dataset and a topic string:

python scripts\research_topic_lab.py "path\to\data.dta" --topic "data resource recognition and corporate reputation"

That is the README's own form, with a Windows path. On a POSIX shell you would swap the backslashes for forward slashes; the flags and argument order stay the same. After the run, the main output is research_topic_lab_report.html, with charts written under charts/ and the supporting CSVs alongside it.

If you already know which columns matter, name them. The README's second example fixes the outcome, the treatment and the control set:

python scripts\research_topic_lab.py "path\to\data.dta" `
  --topic "data resource recognition and corporate reputation" `
  --y ReputationScore `
  --x entry `
  --controls Size Lev ROA Growth BM Board Indep Top1 SOE Cashflow Loss `
  --id firm_id `
  --time year

Supplying --id and --time is what makes the fixed-effect and placebo checks in the second pass possible, so a run without them is a weaker screen. The third documented example adds root-directory scanning and tunes the literature and validation budget:

python scripts\research_topic_lab.py "path\to\data.dta" `
  --topic "data resource recognition and corporate reputation" `
  --scan-root "path\to\project_folder" `
  --literature-top 30 `
  --per-query 8 `
  --deep-top 3 `
  --placebo-reps 200

--scan-root widens brainstorming to other datasets in the folder, --literature-top and --per-query control how much literature is pulled per query family, --deep-top sets how many topics get the second pass, and --placebo-reps sets the permutation repetitions. Before reading the dashboard, open feature_validation_checks.csv. The README calls it mandatory and lists what it verifies: data reading, brainstorming, literature diagnostics, evidence scoring, second-pass validation and chart links.

Where the screening breaks down

The most consequential limitation is that the skill needs data before it can help. It screens topics from an existing .csv or .dta file. If you have an idea and no dataset, there is nothing to profile and nothing to regress, and the tool cannot tell you which data you would need to collect. That is a different problem, and the README does not claim to solve it.

The second limitation is the regressions themselves. The README is direct that screening significance is not causal proof and that a high rank does not make a topic publishable. A first-pass regression on whatever variables happen to be in your file, followed by fixed effects and a placebo check, is a signal about whether the data can say anything at all. It is not identification. If your contribution depends on a design that this pipeline cannot express, the empirical score is measuring something adjacent to what you care about.

The third is the literature layer. Theory scores depend on a search provider returning results. The diagnostics file exists precisely because that can fail, and the README tells you to review literature_evidence.csv and literature_query_diagnostics.csv before relying on theory scores. A provider outage does not produce an error that stops the run; it produces a topic that looks theoretically thin. Read the diagnostics before you believe a low theory support score.

Finally, the README does not document rollback, does not describe how to re-run a previous screening from a saved configuration, and does not state how scores behave when the underlying literature index changes between runs. If you need reproducible scoring across months, treat that as unverified until you check it yourself.

What it replaces, and what the replacement costs

The obvious alternative is the manual workflow: profile the data by hand, read the adjacent literature yourself, run a few regressions, and decide. That workflow has one clear advantage. A human reading twenty papers understands the mechanism and the institutional context, and can tell that two literatures are conceptually close even when they share no vocabulary. The skill's bridge classification depends on concept anchors appearing in the paper text, and the README's own examples (information assets, intellectual capital, data valuation, data disclosure, investor judgment, information environment) are a fixed conceptual neighborhood rather than a general semantic model. A topic whose bridge runs through a literature outside that neighborhood may be scored as having weak theoretical footing when it does not.

What the manual workflow lacks is the audit trail. Every score here has a written record: which query family ran, how many raw hits came back, how many were judged relevant, which evidence class each paper received, and which topics got a second pass with how many permutation repetitions. That record is the actual product. It lets a supervisor or a coauthor see why a topic ranked where it did, and it lets you find the step that went wrong.

The other alternative is a keyword-only topic generator. The README draws that contrast explicitly: older keyword-only tools tend to confuse a topic with no theory footing against a topic with no direct paper but strong bridge support. The first is a dead end. The second is a frontier gap. Separating them is the specific claim this project makes, and it is the claim to test on your own field before accepting the rankings.

Maintenance, licence and the cost of an upgrade

The repository is not archived, and the last push was on 2026-07-04. There are no retrieved releases, so there is no versioned artifact to pin against. The README labels the current state as the first updated version, and the changes it lists are substantial: the HTML dashboard as the primary output rather than a spreadsheet-only workflow, broader brainstorming across nearby datasets, the literature diagnostics file, the four evidence classes, bridge literature treated as theoretically valuable, the evidence_profile field, second-pass validation for the top three, and the mandatory self-audit file. A project whose first update reshapes the output format and the scoring vocabulary is a project where you should expect the report schema to move again.

The practical consequence is upgrade cost. Because outputs are a set of CSV files plus summary.json plus the HTML report, any change to field names or score definitions invalidates comparisons between an old run and a new one. If you keep screening results across a thesis, archive the whole output directory per run rather than only the HTML, and record the commit you ran.

The licence is MIT, which permits commercial and academic reuse and modification with the licence and copyright notice retained. Nothing in the README addresses citation of the tool itself, and it does not discuss data protection. If your .dta file is restricted or contains personal data, the literature search step sends topic strings derived from your variables to an external provider, which is a disclosure decision you should make deliberately rather than by default. That is not legal advice; it is a question to put to whoever governs your data.

Editorial conclusion

Adopt it if you already hold a usable .csv or .dta dataset, work in accounting, finance, economics, management, corporate governance, digital transformation, ESG, audit, disclosure or capital-market research, and want a ranked shortlist with an audit trail before committing months to one idea. Skip it if you have no data yet, if your question needs causal identification rather than a screening signal, or if you need a search provider the skill can reach and cannot configure one. Before trusting any report, open feature_validation_checks.csv, then literature_evidence.csv and literature_query_diagnostics.csv, and confirm that the variables the score leans on are the ones you would actually defend in a seminar.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. lzh-phd/topic-feasibility-screener on GitHub
4. README