{"id":50530594,"url":"https://github.com/apartsinprojects/coreason","last_synced_at":"2026-06-03T13:01:35.926Z","repository":{"id":361763942,"uuid":"1182499343","full_name":"ApartsinProjects/CoReason","owner":"ApartsinProjects","description":"CoReasoning: an assessable competency model (Framing, Judging, Steering) for reasoning with generative AI — paper, instrument, data (open-source, MIT)","archived":false,"fork":false,"pushed_at":"2026-06-01T07:06:56.000Z","size":7880,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-01T07:24:33.891Z","etag":null,"topics":["ai-in-education","ai-literacy","educational-technology","generative-ai","llm","metacognition"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ApartsinProjects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T15:53:05.000Z","updated_at":"2026-06-01T07:07:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ApartsinProjects/CoReason","commit_stats":null,"previous_names":["apartsinprojects/coreason"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ApartsinProjects/CoReason","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApartsinProjects%2FCoReason","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApartsinProjects%2FCoReason/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApartsinProjects%2FCoReason/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApartsinProjects%2FCoReason/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ApartsinProjects","download_url":"https://codeload.github.com/ApartsinProjects/CoReason/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ApartsinProjects%2FCoReason/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33865655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-in-education","ai-literacy","educational-technology","generative-ai","llm","metacognition"],"created_at":"2026-06-03T13:01:32.753Z","updated_at":"2026-06-03T13:01:35.921Z","avatar_url":"https://github.com/ApartsinProjects.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CoReasoning\n\n### 📄 Read the paper: **[apartsinprojects.github.io/CoReason](https://apartsinprojects.github.io/CoReason/)**  ·  [Word (.docx)](docs/coreasoning.docx)  ·  [Markdown source](paper/coreasoning.md)\n\n![CoReasoning hero](docs/assets/hero-gemini-coreasoning.png)\n\n**Teaching and assessing the skill of working with generative AI**, decomposed into three\nindependently-assessable competencies: **Framing**, **Judging**, and **Steering**.\n\n\u003e Most AI-in-education tools optimize for speed-to-answer. CoReasoning optimizes for\n\u003e quality-of-thinking: learners improve intentionally imperfect AI output through structured reasoning\n\u003e loops, and the three skills are scored separately.\n\n## 📄 Paper (open-source, MIT)\n\n**\"Framing, Judging, Steering: An Assessable Competency Model for Teaching Students to Reason With\nGenerative AI\"** by Alexander Apartsin (Holon Institute of Technology) and Yehudit Aperstein (Afeka\nCollege of Engineering).\n\nA theoretically-grounded competency model with a proof-of-concept instrument and a feasibility\ndemonstration that the three skills **dissociate**: own-skill grade effects average +1.02 versus +0.01\nfor cross-skill effects (N=80 across 10 subjects; the cleanest pair, Framing and Judging, is\nuncorrelated, ρ=−0.03 ns), the result replicates across grader backends, and the grader is 92%\nself-consistent. No learning-outcome claims are made; a human-rater validation study is prepared.\n\n- 📖 **Read it (HTML + KaTeX):** \u003chttps://apartsinprojects.github.io/CoReason/\u003e\n- 📝 **Word:** [`docs/coreasoning.docx`](docs/coreasoning.docx) · **Source:** [`paper/coreasoning.md`](paper/coreasoning.md)\n- 📚 **Bibliography:** [`paper/references.bib`](paper/references.bib) (55 entries, validated)\n- ✉️ **Submission package:** [`paper/SUBMISSION/`](paper/SUBMISSION/) (cover letter + anticipated reviewer response)\n\n## The framework\n\n- **Framing**: turn an ill-defined problem into a well-specified task *before* invoking AI.\n- **Judging**: critically evaluate AI output for errors, gaps, unstated assumptions, and risk.\n- **Steering**: iteratively redirect the AI toward a better solution across cycles.\n\nThe defining move is separating the *pre-generation* skill (Framing) from the *post-generation*\ncorrective skill (Steering), which prior frameworks fuse under \"prompting.\" Each skill is grounded in\nestablished theory (metacognitive monitoring and control, self-regulated learning, epistemic vigilance,\nproductive struggle), and the model states five testable propositions about how the skills relate.\n\n## The instrument and CoReasoning Lab\n\nCoReasoning Lab is a **runnable open-source learning platform** that auto-generates ill-defined problems\nwith seeded flaws, presents deliberately-imperfect AI output, runs judge-and-steer cycles, and scores\nthe three skills with rubric-driven LLM evaluators.\n\n- **Full platform** (Node/Express + SQLite/Postgres, Knex migrations, Passport auth, Docker, Playwright\n  e2e, a five-language content library) is on the [`staging`](../../tree/staging) branch:\n  `npm install \u0026\u0026 npm run db:setup \u0026\u0026 npm start` (or `npm run docker:dev`).\n- **System documentation** (on this branch): [`docs/CONOPS.md`](docs/CONOPS.md) (concept of operations),\n  [`docs/spec/SPEC.md`](docs/spec/SPEC.md) + 12 flow specs, 7 personas, and UX audits; the\n  `staging` branch adds instructor/student/developer guides, a `pedagogy.md` learning-theory mapping,\n  and real session logs.\n- **The scoring engine** evaluated in the paper is the sixteen prompts at\n  `code/artifacts/prompt-debug/originals/*.yaml` (the deployed app's evaluation logic), exercised by the\n  harness in `research/`.\n\n**Educators can run it now, no web app needed.** `code/run_session.py` scores a real student's\nFraming, Judging, and Steering over the real engine and returns three rubric-driven grades with\nper-criterion feedback. See [`code/README_EDUCATORS.md`](code/README_EDUCATORS.md):\n\n```bash\npython code/run_session.py --subject \"Statistics \u003e Hypothesis Testing\" --interactive   # live with a student\npython code/run_session.py --subject \"Algorithms \u003e Sorting \u0026 Searching\" --demo          # see it work\n```\n\n## Repository map\n\n```text\npaper/            manuscript (coreasoning.md), references.bib, figures, build_html.py, SUBMISSION/, reviews/\ndocs/             rendered site: index.html (KaTeX), coreasoning.docx, assets/ (served via GitHub Pages)\nresearch/\n  scripts/        reproducible harness: harness.py, e3_dissociation.py, e3_expand.py,\n                  e2_reliability.py, e1_analysis.py, make_figures.py, render_bib.py, batch_openai.py\n  results/        grades CSVs + analysis JSONs (N=80 + ablations + robustness)\n  experiments/    registry: PROJECT_LOG.md, INDEX.md\n  DATASHEET.md    dataset documentation (Gebru-style)\nhuman-study/      prepared 3-rater study: README, CODEBOOK, seeded samplers + scorers, task files\ncode/run_session.py   educator runner: score a real student over the engine (README_EDUCATORS.md)\ncode/artifacts/prompt-debug/originals/   the sixteen-prompt scoring instrument (YAML)\ndocs/             CONOPS, SPEC + flow specs, personas, UX audits\nscreens/          static UI renders; the full runnable app is on the `staging` branch\n```\n\n## Reproduce\n\nAPI keys live outside the repo (never committed). Provide them in `~/.config/coreason/.env.all` (or set\n`COREASON_ENV_FILE`), with `OPENAI_API_KEY` and/or `OPENROUTER_API_KEY` / `GROQ_API_KEY`.\n\n```bash\n# dissociation (N=80 across 10 subjects) + analyses\nCOREASON_GRADER=openai:gpt-4o python research/scripts/e3_dissociation.py 5   # 5 subjects\nCOREASON_GRADER=openai:gpt-4o python research/scripts/e3_expand.py           # +5 subjects -\u003e N=80\npython research/scripts/e1_analysis.py research/results/e3_dissociation_grades.csv\nCOREASON_GRADER=openai:gpt-4o python research/scripts/e2_reliability.py      # grader test-retest\npython research/scripts/make_figures.py                                     # regenerate figures\npython paper/build_html.py                                                  # rebuild docs/index.html\n```\n\nA deterministic disk cache (`research/data/llm_cache/`) makes runs reproducible and free on re-run.\nSee [`research/README.md`](research/README.md) and [`research/experiments/INDEX.md`](research/experiments/INDEX.md)\nfor the full experiment list.\n\n## Status\n\nThe conceptual paper and the feasibility demonstration (E1 construct validity, E2 reliability, E3\ndissociation at N=80, E4 ground-truth ablation, grader-backend robustness, a harsher-steering ablation,\nand per-subject breakdowns) are complete. The one open item is the **human-rater agreement study**,\nfully prepared in [`human-study/`](human-study/CODEBOOK.md) and requiring human graders. No\nlearning-outcome claims are made.\n\n## License\n\n[MIT](LICENSE). The system design, the instrument, the harness, the data, and the figures are\nopen-source. The hero image was generated with the Google Gemini Image API.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapartsinprojects%2Fcoreason","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapartsinprojects%2Fcoreason","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapartsinprojects%2Fcoreason/lists"}