Research repository restructure plan

[0xjei]

Discussed in #16

^{Originally posted by 0xjei July 16, 2025}
hey folks, this is a proposal for restructuring the Research repository. The following has been already reviewed by @Msiusko but any feedback, comments or ideas are more than welcome. Thank you in advance!

Motivation

The current state of research repository is fragmented and unsustainable. Research assets, initiatives, and outputs are dispersed across multiple platforms—ranging from repositories and websites to duplicated files, text documents, markdowns, and scattered infographics. This lack of structure results in redundancy and hinders discoverability, collaboration, and maintenance. Moreover, the fragmented presentation conveys an unprofessional image to partners and potential investors, complicating fundraising efforts by obscuring our goals and capabilities.

For example, this research repository is basically empty, there's a bunch of items on the board which is not updated since 7months, docs and website reflect an outdated view.

Goals

My initiative focuses on internal consolidation and standardization as a prerequisite to external collaboration. By modeling best practices internally, we aim to establish a clear, coherent map of existing research, implement consistent structures, and introduce lightweight workflows that improve both quality and productivity.

1. Consolidate: Centralize all existing research artifacts in a unified location.
2. Structure: Apply consistent organizational schemas and naming conventions.
3. Streamline: Implement efficient internal workflows aligned with the current team’s needs.
4. Clarify: Improve navigation and comprehension of research to support alignment and contributions across the team.

Repository Structure

To support clarity, consistency, and ease of collaboration, the following structure is proposed:

/research
├── README.md                     # Overview and navigation guide
├── CONTRIBUTING.md               # Internal contribution guide
├── /.github/                     # Templates for issues and pull requests
│   ├── ISSUE_TEMPLATE.md
│   └── PULL_REQUEST_TEMPLATE.md
│
├── /templates/                   # Templates for initiating new research
│   └── research-initiative.md
│
├── /initiatives/                 # Canonical directory for all research initiatives
│   ├── ethereum-privacy-ecosystem/
│   │   ├── ethereum-privacy-ecosystem.md
│   │   ├── /assets/              # Visuals and diagrams
│   │   ├── /notes/               # Drafts and meeting notes
│   │   ├── /resources/           # Datasets, other (e.g., EIPS, Hackathon)
│   │   └── /publications/        # Final outputs (PDFs, whitepapers)
│   ├── privacy-landscape-map/
│   ├── scoring-model/
│   ├── annual-market-report/
│   └── [other-initiatives]/
│
├── /shared-resources/           # Assets reused across initiatives
│   ├── /assets/                 # Logos, shared visuals
│   ├── /resource-X/             # Specific shared resource (can have multiple of this)
│   └── /data/                   # Shared data
│
└── /archive/                    # Deprecated or legacy research

This modular structure is lightweight and extensible, built to evolve with the team while enforcing a baseline of consistency. Indeed, this could be developed to accommodate more complexity in the future without causing any disruption (for example, adding a subfolder to 'initiatives/initiative-1' would not affect the others).

Internal Research Workflow

This workflow is designed to promote transparency, accountability, and rigor across all research efforts.

Metadata Standard

Each research initiative must include a canonical .md file beginning with a standardized YAML block:

---
title: Research Initiative Title
status: draft                   # draft | active | review | final | paused
created: 2025-07-13
updated: 2025-07-13
authors: [@username1, @username2]
category: ecosystem-analysis    # ecosystem-analysis | tooling | policy | market-research
timeline: Q2 2025
priority: high                  # high | medium | low
---

This metadata underpins searchability, prioritization, and governance across the repository.

Team Responsibilities

Each team member is responsible for the full lifecycle of their research—owning not just the outputs, but also their upkeep. Responsibilities include:

• Maintaining up-to-date metadata
• Structuring content in line with standards
• Organizing assets and notes
• Responding to review feedback

At the same time, accountability is distributed across authors, reviewers, and research lead.

Contribution Process (Internal)

Research development occurs through GitHub Pull Requests to ensure traceability and review.

Researchers must:

• Create a folder under /initiatives/ using the standard structure
• Use /notes/ for drafts, and maintain a clean canonical principal .md file from a template
  • the different kind of templates will be designed taking into consideration current research documents sections and, industry standards (e.g., every .md should specify the goal, process and expectations of research).
  • use the resources/ folder to manage all the consistent outputs of the research (e.g., EIPS).
• Keep metadata updated (especially status and updated)
• Submit changes via PRs and request peer review from selected reviewers
  • we are not currently taking into consideration a “real” review process since everything is still internally supervised.
• Mark the document as final once approved

To reduce the complexity of navigating a file-based system, a GitHub Project Board will serve as the primary dashboard for research tracking. The board integrates directly with GitHub issues and PRs, allowing filtering by researcher, reviewer, status, and more.

A simple, yet-effective initial columns set would be the following:

• Planning – Proposed initiatives or not yet started
• Ongoing – Actively being researched
• Reviewing – Awaiting reviews or revisions during their lifecycle
• Completed – Finalized and merged to main branch (ie., visible when someone opens the repository straight away).

This view provides a streamlined, real-time understanding of the entire research pipeline without the burden of an internal website.

---

Timeline & Expectations

Given summer schedules and my limited bandwidth, this process is expected to unfold gradually. While this plan has been drafted quickly and may require adjustment, the goal is to have the full internal system functional by late September 2025.

The following is an incomplete list of things to do, grouped by milestone:

Foundation Setup

• Establish core repository structure
• Draft README.md and CONTRIBUTING.md
• Create initiative and metadata templates
• Inventory all existing research

Content Migration

• Create initiative folders
• Migrate research from existing sources
• Apply metadata and clean redundancies
• Launch project board

Team Onboarding

• Present new structure to the team
• Pilot workflow with Ethereum Privacy Ecosystem
• Begin adoption for current initiatives
• Collect team feedback & refine structure based on real usage

Success Criteria

This internal rework will be considered successful when:

• All research is consolidated within the repository
• Team members can reliably locate and contribute to research
• A shared structure is consistently applied
• The team adopts and uses the new workflow
• The repository presents a polished and professional public face

---